<!-- BusyBot node reference — https://busybot.net/tools/iterable/ -->

> Node: Iterable (`iterable`) · Action · v1
> Category: Communication · Credentials: Iterable API (`iterableApi`)
> Updated: 2026-08-16

# Iterable

> Manage users, track events, and manage list subscriptions on Iterable

## Overview

Iterable is a cross-channel marketing platform. This tool can create/update/delete/get users, track custom events, and add/remove users from lists. Authentication is via API key sent as an Api_Key header. Supports US and EU data center regions.

**Category:** Communication  
**Tool Name:** `iterable`  
**Version:** 1

**Appearance:** Icon: `lucide-Mail` | Color: `#5CC8C8`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Iterable API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/iterable-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Event | `event` |
| User | `user` |
| User List | `userList` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Track | `track` | Record the actions a user performs (Event resource) |
| Create or Update | `upsert` | Create a new user, or update the current one if it already exists (User resource) |
| Delete | `delete` | Delete a user (User resource) |
| Get | `get` | Get a user (User resource) |
| Add | `add` | Add user to list (User List resource) |
| Remove | `remove` | Remove a user from a list (User List resource) |

### Parameters

#### Event: Track

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Event Name | `string` | Yes | — | The name of the event to track. Supports expressions like {{ $json.eventName }}. |
| Additional Fields | `collection` | No | `{}` | Optional event attributes. Add only the ones you need. |
| — Campaign ID | `string` | No | — | Campaign tied to conversion. |
| — Created At | `string` | No | — | Time the event happened (ISO 8601 datetime string). Will be converted to Unix timestamp. |
| — Data Fields | `fixedCollection` | No | `{}` | Custom key/value data stored with the event. Add one entry per field. |
| — — Key | `string` | No | — | The key for the event data field. |
| — — Value | `string` | No | — | The value for the event data field. |
| — Email | `string` | No | — | Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence. |
| — Event ID | `string` | No | — | Optional event ID. If an event exists with that ID, the event will be updated. If none is specified, a new ID will automatically be generated. |
| — Template ID | `string` | No | — | Template ID associated with this event. |
| — User ID | `string` | No | — | userId that was passed into the updateUser call. |

#### User: Create or Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Identifier | `options` | Yes | `email` | Identifier to be used. |
| | | | | Options: `email`, `userId` |
| Value | `string` | Yes | — | The email address or user ID value. Supports expressions like {{ $json.email }}. |
| Create If Doesn't Exist | `boolean` | Yes | `true` | Whether to create a new user if the identifier does not exist. _(shown when Identifier is `userId`)_ |
| Additional Fields | `collection` | No | `{}` | Optional user attributes. Add only the ones you need. |
| — Data Fields | `fixedCollection` | No | `{}` | Custom key/value data stored on the user profile. Add one entry per field. |
| — — Key | `string` | No | — | The key for the user data field. |
| — — Value | `string` | No | — | The value for the user data field. |
| — Merge Nested Objects | `boolean` | No | `false` | Whether to merge top level objects instead of overwriting (default: false). For example, if user profile has data: {mySettings:{mobile:true}} and the update has data: {mySettings:{email:true}}, the result will be: {mySettings:{mobile:true,email:true}}. |

#### User: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| By | `options` | Yes | `email` | Identifier to be used. |
| | | | | Options: `email`, `userId` |
| Email | `string` | Yes | — | Email for the user to delete. Supports expressions. _(shown when By is `email`)_ |
| User ID | `string` | Yes | — | Unique identifier for the user to delete. Supports expressions. _(shown when By is `userId`)_ |

#### User: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| By | `options` | Yes | `email` | Identifier to be used. |
| | | | | Options: `email`, `userId` |
| Email | `string` | Yes | — | Email for the user to retrieve. Supports expressions. _(shown when By is `email`)_ |
| User ID | `string` | Yes | — | Unique identifier for the user to retrieve. Supports expressions. _(shown when By is `userId`)_ |

#### User List: Add

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| List ID | `string` | Yes | — | The numeric ID of the list. Find list IDs via the Iterable dashboard under Audience > Lists, or by calling GET /api/lists. |
| Identifier | `options` | Yes | `email` | Identifier to be used. |
| | | | | Options: `email`, `userId` |
| Value | `string` | Yes | — | The email address or user ID to add to the list. Supports expressions. |

#### User List: Remove

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| List ID | `string` | Yes | — | The numeric ID of the list. Find list IDs via the Iterable dashboard under Audience > Lists, or by calling GET /api/lists. |
| Identifier | `options` | Yes | `email` | Identifier to be used. |
| | | | | Options: `email`, `userId` |
| Value | `string` | Yes | — | The email address or user ID to remove from the list. Supports expressions. |
| Additional Fields | `collection` | No | `{}` | Optional unsubscribe attributes. |
| — Campaign ID | `number` | No | `0` | Attribute unsubscribe to a specific campaign. |
| — Channel Unsubscribe | `boolean` | No | `false` | Whether to unsubscribe email from list's associated channel - essentially a global unsubscribe. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item — no operation fans out. The Iterable API response is merged into the incoming item JSON at the top level, so the fields you sent in pass through and binary data is forwarded. If the API returns something that is not an object, it lands on a `result` property instead.

| Operation | What lands on the item |
|-----------|------------------------|
| `track` | Iterable's acknowledgement of the tracked event. |
| `upsert` | Iterable's update response. A response body that reports a non-success code is raised as an item error rather than passed through. |
| `delete` | Iterable's delete response, likewise checked for a success code. |
| `get` | The user record itself — the surrounding `user` wrapper is unwrapped before output. A user that does not exist raises a `User not found` item error, so a successful item always has a real profile on it. |
| `add` / `remove` | Iterable's subscribe / unsubscribe response. |

## Usage Examples

- Create or update a user in Iterable by email
- Track a custom event for an Iterable user
- Subscribe users to an Iterable mailing list
- Delete a user from Iterable by user ID
- Get user details from Iterable by email

## Example Configuration

Track a custom event with data fields:

```json
{
  "type": "iterable",
  "parameters": {
    "resource": "event",
    "operation": "track",
    "name": "purchase_completed",
    "additionalFields": {
      "email": "{{ $json.email }}",
      "campaignId": "campaign_abc",
      "dataFieldsUi": {
        "dataFieldValues": [
          { "key": "product_id", "value": "prod_123" },
          { "key": "amount", "value": "29.99" }
        ]
      }
    }
  }
}
```

Create or update a user identified by email:

```json
{
  "type": "iterable",
  "parameters": {
    "resource": "user",
    "operation": "upsert",
    "identifier": "email",
    "value": "newuser@example.com",
    "additionalFields": {
      "dataFieldsUi": {
        "dataFieldValues": [
          { "key": "firstName", "value": "John" },
          { "key": "lastName", "value": "Doe" }
        ]
      },
      "mergeNestedObjects": true
    }
  }
}
```

Create or update by user ID, creating the profile when it is new:

```json
{
  "type": "iterable",
  "parameters": {
    "resource": "user",
    "operation": "upsert",
    "identifier": "userId",
    "value": "user_12345",
    "preferUserId": true,
    "additionalFields": {
      "dataFieldsUi": {
        "dataFieldValues": [
          { "key": "subscription_tier", "value": "premium" }
        ]
      }
    }
  }
}
```

Fetch a user by user ID:

```json
{
  "type": "iterable",
  "parameters": {
    "resource": "user",
    "operation": "get",
    "by": "userId",
    "userId": "user_67890"
  }
}
```

Delete a user by email:

```json
{
  "type": "iterable",
  "parameters": {
    "resource": "user",
    "operation": "delete",
    "by": "email",
    "email": "user.to.delete@example.com"
  }
}
```

Subscribe an address to a list:

```json
{
  "type": "iterable",
  "parameters": {
    "resource": "userList",
    "operation": "add",
    "listId": "123456",
    "identifier": "email",
    "value": "{{ $json.email }}"
  }
}
```

Unsubscribe with campaign attribution and a channel-wide opt-out:

```json
{
  "type": "iterable",
  "parameters": {
    "resource": "userList",
    "operation": "remove",
    "listId": "123456",
    "identifier": "userId",
    "value": "user_99999",
    "additionalFields": {
      "campaignId": 789,
      "channelUnsubscribe": true
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Use Iterable to manage users, track events, and manage mailing list subscriptions on the Iterable marketing platform.

### Data Fields Pattern

When using `dataFieldsUi` in `additionalFields`, always structure as:

```json
{
  "dataFieldsUi": {
    "dataFieldValues": [
      {
        "key": "field_name",
        "value": "field_value"
      }
    ]
  }
}
```

This structure allows you to pass custom data fields that will be stored with the user or event in Iterable.

### Notes

- **Identify the user on every event.** Track sends the identifiers you put in Additional Fields — supply Email or User ID. When both are present, email takes precedence.
- **Create If Doesn't Exist only appears for User ID.** Upserting by email always creates the profile when it is missing; the flag exists because a bare user ID would otherwise be ambiguous.
- **Merge Nested Objects changes update semantics.** Off, a nested object on the profile is replaced wholesale by the one you send; on, the two are merged key by key.
- **List ID is numeric.** Take it from Audience > Lists in the Iterable dashboard, not the list name.