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 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:

{
  "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:

{
  "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:

{
  "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:

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

Delete a user by email:

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

Subscribe an address to a list:

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

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

{
  "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:

{
  "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.