Iterable

App · 25 actions

Manage users, events and list subscriptions, inspect campaigns and templates, and send email or SMS from Iterable campaigns.

Actions

ActionWhat it does
Create listCreate a static list.
Delete listDelete a list.
Delete user by IDDelete a user profile by its user ID.
Get campaignGet a campaign.
Get campaign metricsGet metrics for campaigns.
Get email templateGet an email template by templateId.
Get list sizeGet count of users in list.
Get userGet a user by email (query parameter).
Get user by idGet a user by userId (path parameter).
List campaignsList campaign metadata.
List channelsGet channels.
List journeysGet journeys (workflows).
List listsGet lists.
List message typesList message types.
List subscribersGet users in a list.
List templatesGet project templates.
List user eventsGet user events.
List user events by idGet user events by userId.
Send emailSend an email to an email address.
Send smsSend SMS notification to user.
Subscribe usersAdd subscribers to list.
Track eventTrack an event.
Unsubscribe usersRemove users from a list.
Update subscriptionsUpdate user subscriptions.
Update userUpdate user data.

Create list

Create a static list.

Inputs

Descriptiondescriptiontext
Description.
NamenametextRequired
Name.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "listId": 1
  }
}

Delete list

Delete a list.

Inputs

ListlistIdnumberRequired
list id

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "code": "Success",
    "msg": "example",
    "params": {}
  }
}

Delete user by ID

Delete a user profile by its user ID. This permanently removes the profile.

Inputs

User IDuserIdtextRequired
The user ID of the profile to delete.

Outputs

dataobject
The deletion result returned by Iterable.
Example output
{
  "data": {}
}

Get campaign

Get a campaign.

Inputs

IDidnumberRequired
Campaign ID

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "campaignState": "Draft",
    "createdAt": 1,
    "createdByUserId": "example",
    "endedAt": 1,
    "id": 1.0,
    "labelIds": [],
    "labels": [],
    "listIds": [],
    "messageMedium": "example",
    "name": "example",
    "recurringCampaignId": 1.0,
    "sendSize": 1.0,
    "startAt": 1,
    "suppressionListIds": [],
    "templateId": 1.0,
    "type": "Blast",
    "updatedAt": 1,
    "updatedByUserId": "example",
    "workflowId": 1.0
  }
}

Get campaign metrics

Get metrics for campaigns.

Inputs

CampaigncampaignIdlistRequired
Campaign(s) to export
StartDateTimestartDateTimedate and time
Export starting from (>=). Accepted formats include YYYY-MM-DD and other ISO 8601 formats.
EndDateTimeendDateTimedate and time
Export ending at (<). Accepted formats include YYYY-MM-DD and other ISO 8601 formats.

Outputs

datatext
The report returned by Iterable as text.
Example output
{
  "data": "example"
}

Get email template

Get an email template by templateId.

Inputs

TemplateIdtemplateIdnumberRequired
Template ID
Localelocaletext
Locale of content to get

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "bccEmails": [],
    "cacheDataFeed": {},
    "campaignDataFields": {},
    "ccEmails": [],
    "clientTemplateId": "example",
    "creatorUserId": "example",
    "dataFeedId": 1.0,
    "dataFeedIds": [],
    "fromEmail": "example",
    "fromName": "example",
    "googleAnalyticsCampaignName": "example",
    "html": "example",
    "isDefaultLocale": false,
    "linkParams": [],
    "locale": "example",
    "mergeDataFeedContext": {},
    "messageTypeId": 1.0,
    "metadata": {
      "campaignId": 1,
      "clientTemplateId": "example",
      "createdAt": "example",
      "creatorUserId": "example",
      "messageTypeId": 1,
      "name": "example",
      "templateId": 1,
      "updatedAt": "example"
    },
    "name": "example",
    "plainText": "example",
    "preheaderText": "example",
    "replyToEmail": "example",
    "shortenLinks": false,
    "subject": "example",
    "templateId": 1
  }
}

Get list size

Get count of users in list.

Inputs

ListlistIdnumberRequired
list id

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {}
}

Get user

Get a user by email (query parameter).

Inputs

Emailemailtext
Email

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "user": {
      "dataFields": {},
      "email": "example",
      "userId": "example"
    }
  }
}

Get user by id

Get a user by userId (path parameter).

Inputs

User IDuserIdtextRequired
userId

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "user": {
      "dataFields": {},
      "email": "example",
      "userId": "example"
    }
  }
}

List campaigns

List campaign metadata.

Inputs

Pagepagenumber
Page number (starting at 1).At least 1.
PageSizepageSizenumber
Number of results to return per page (defaults to 20, maximum of 1000).
Sortsorttext
Field to sort campaigns by, with optional direction prefix. Use - for descending, + or no prefix for ascending. Campaigns can be sorted by id, name, createdAt, updatedAt, or startAt. Examples: -createdAt, +name, idDefault: id.
CampaignStatecampaignStatelist
Filter campaigns by state. Can be specified multiple times to filter by multiple states. Valid states: Draft, Ready, Scheduled, Running, Finished, Starting, Aborted, Recurring, Archived. Example: ?campaignState=Ready&campaignState=Running

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "campaigns": [],
    "nextPageUrl": "example",
    "previousPageUrl": "example",
    "totalCampaignsCount": {}
  }
}

List channels

Get channels.

Inputs

None.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "channels": []
  }
}

List journeys

Get journeys (workflows).

Inputs

Pagepagenumber
Page number (starting at 1).At least 1.
PageSizepageSizenumber
Number of results to return per page (defaults to 10, maximum of 50).
Sortsorttext
Sort field with optional direction prefix. Use - for descending, + or no prefix for ascending. Examples: -createdAt, +name, idDefault: id.
Statestatelist
Without this parameter, the endpoint returns all non-archived journeys. With state set to Archived, the endpoint only returns archived journeys.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "journeys": [],
    "nextPageUrl": "example",
    "previousPageUrl": "example",
    "totalJourneysCount": 1
  }
}

List lists

Get lists.

Inputs

None.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "lists": []
  }
}

List message types

List message types.

Inputs

None.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "messageTypes": []
  }
}

List subscribers

Get users in a list.

Inputs

ListlistIdnumberRequired
list id
PreferUserIdpreferUserIdtrue/false
If true, will return the userId instead of email if both exists in a user profile for a hybrid project.Default: false.

Outputs

datatext
The report returned by Iterable as text.
Example output
{
  "data": "example"
}

List templates

Get project templates.

Inputs

TemplateTypetemplateTypetext
Only retrieve templates associated with this template typeOne of: Base, Blast, Triggered, Workflow.
MessageMediummessageMediumtext
Only retrieve templates associated with this message mediumOne of: Email, Push, InApp, SMS.
StartDateTimestartDateTimedate and time
Get templates created at or after this date time (yyyy-MM-dd HH:mm:ss [ZZ])
EndDateTimeendDateTimedate and time
Get templates created before this date time (yyyy-MM-dd HH:mm:ss [ZZ])
Pagepagenumber
Page number (starting at 1).At least 1. Default: 1.
PageSizepageSizenumber
Number of results to return per page (defaults to 20, maximum of 1000).Default: 20.
Sortsorttext
Field to sort templates by, with optional direction prefix. Use - for descending, + or no prefix for ascending. Templates can be sorted by id, name, createdAt, or updatedAt. Examples: -createdAt, +name, idDefault: id.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "nextPageUrl": "example",
    "previousPageUrl": "example",
    "templates": [],
    "totalTemplatesCount": {}
  }
}

List user events

Get user events.

Inputs

EmailemailtextRequired
Email of the user whose events you are retrieving.
Limitlimitnumber
The number of events to retrieve. (Max is 200)From 1 to 200. Default: 25.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "events": []
  }
}

List user events by id

Get user events by userId.

Inputs

User IDuserIdtextRequired
UserId of the user whose events you are retrieving.
Limitlimitnumber
The number of events to retrieve. (Max is 200)From 1 to 200. Default: 25.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "events": []
  }
}

Send email

Send an email to an email address.

Inputs

AllowRepeatMarketingSendsallowRepeatMarketingSendstrue/false
Allow repeat marketing sends? Defaults to true.
CampaigncampaignIdnumberRequired
Campaign ID
DataFieldsdataFieldsobject
Fields to merge into email template
Metadatametadataobject
Metadata to pass back via webhooks. Not used for rendering
RecipientEmailrecipientEmailtext
An email address that identifies a user profile in Iterable. Provide a recipientEmail or a recipientUserId (but not both), depending on how your project identifies users.
RecipientUserIdrecipientUserIdtext
A user ID that identifies a user profile in Iterable. Provide a recipientEmail or a recipientUserId (but not both), depending on how your project identifies users.
SendAtsendAtdate and time
Schedule the message for up to 365 days in the future. If set in the past, email is sent immediately. Format is YYYY-MM-DD HH:MM:SS in UTC

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "code": "Success",
    "msg": "example",
    "params": {}
  }
}

Send sms

Send SMS notification to user.

Inputs

AllowRepeatMarketingSendsallowRepeatMarketingSendstrue/false
Allow repeat marketing sends? Defaults to true.
CampaigncampaignIdnumberRequired
Campaign ID
DataFieldsdataFieldsobject
Fields to merge into template
RecipientEmailrecipientEmailtext
An email address that identifies a user profile in Iterable. Provide a recipientEmail or a recipientUserId (but not both), depending on how your project identifies users.
RecipientUserIdrecipientUserIdtext
A user ID that identifies a user profile in Iterable. Provide a recipientEmail or a recipientUserId (but not both), depending on how your project identifies users.
SendAtsendAtdate and time
Schedule the message for up to 365 days in the future. If set in the past, message is sent immediately. Format is YYYY-MM-DD HH:MM:SS in UTC

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "code": "Success",
    "msg": "example",
    "params": {}
  }
}

Subscribe users

Add subscribers to list.

Inputs

ListlistIdnumberRequired
Listid.
SubscriberssubscriberslistRequired
Subscribers.
UpdateExistingUsersOnlyupdateExistingUsersOnlytrue/false
Whether to skip operation when the request includes a userId or email that doesn't yet exist in the Iterable project. When true, Iterable ignores requests with unknown userIds and email addresses. When false, Iterable creates new users. Defaults to false. Only respected in API calls for userID-based and hybrid projects.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "createdFields": [],
    "failCount": 1,
    "failedUpdates": {
      "conflictEmails": [],
      "conflictUserIds": [],
      "forgottenEmails": [],
      "forgottenUserIds": [],
      "invalidDataEmails": [],
      "invalidDataUserIds": [],
      "invalidEmails": [],
      "invalidUserIds": [],
      "notFoundEmails": [],
      "notFoundUserIds": []
    },
    "filteredOutFields": [],
    "invalidEmails": [],
    "invalidUserIds": [],
    "successCount": 1
  }
}

Track event

Track an event.

Inputs

CampaigncampaignIdnumber
Campaign tied to conversion
CreateNewFieldscreateNewFieldstrue/false
Whether new fields should be ingested and added to the schema. Defaults to project's setting to allow or drop unrecognized fields.
CreatedAtcreatedAtdate and time
When the event happened. Leave blank to use the time Iterable receives it.
DataFieldsdataFieldsobject
Additional data associated with event (i.e. item amount, item quantity). For events of the same name, identically named data fields must be of the same type.
Emailemailtext
An email address that identifies a user profile in Iterable. Provide an email or a userId (but not both), depending on how your project identifies users.
EventNameeventNametextRequired
Name of event
IDidtext
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 and returned. Note that this ID cannot be longer than 512 bytes.
TemplateIdtemplateIdnumber
Template id
User IDuserIdtext
A user ID that identifies a user profile in Iterable. Provide an email or a userId (but not both), depending on how your project identifies users.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "code": "Success",
    "msg": "example",
    "params": {}
  }
}

Unsubscribe users

Remove users from a list.

Inputs

CampaigncampaignIdnumber
attribute unsubscribe to a campaign
ChannelUnsubscribechannelUnsubscribetrue/false
Unsubscribe email from list's associated channel - essentially a global unsubscribe. (default: false)
ListlistIdnumberRequired
Listid.
SubscriberssubscriberslistRequired
Subscribers.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "createdFields": [],
    "failCount": 1,
    "failedUpdates": {
      "conflictEmails": [],
      "conflictUserIds": [],
      "forgottenEmails": [],
      "forgottenUserIds": [],
      "invalidDataEmails": [],
      "invalidDataUserIds": [],
      "invalidEmails": [],
      "invalidUserIds": [],
      "notFoundEmails": [],
      "notFoundUserIds": []
    },
    "filteredOutFields": [],
    "invalidEmails": [],
    "invalidUserIds": [],
    "successCount": 1
  }
}

Update subscriptions

Update user subscriptions.

Inputs

CampaigncampaignIdnumber
Campaign to attribute unsubscribes
Emailemailtext
An email address that identifies a user profile in Iterable. For each user in your request, provide an email or a userId (but not both), depending on how your project identifies users.
EmailListIdsemailListIdslist
Lists that a user is subscribed to
SubscribedMessageTypeIdssubscribedMessageTypeIdslist
Individual message type IDs to subscribe (does not impact channel subscriptions). To set a value for this field, first have your CSM enable the opt-in message types feature. Otherwise, attempting to set this field causes an error.
TemplateIdtemplateIdnumber
Template to attribute unsubscribes
UnsubscribedChannelIdsunsubscribedChannelIdslist
Email channel ids to unsubscribe from
UnsubscribedMessageTypeIdsunsubscribedMessageTypeIdslist
Individual message type IDs to unsubscribe (does not impact channel subscriptions).
User IDuserIdtext
A user ID that identifies a user profile in Iterable. For each user in your request, provide an email or a userId (but not both), depending on how your project identifies users.
ValidateChannelAlignmentvalidateChannelAlignmenttrue/false
Defaults to true (validation enabled). When false, allows subscribing users to message types that belong to unsubscribed channels. By default, Iterable validates that subscribed message types belong to subscribed channels. Setting this to false bypasses this validation, allowing you to save message type preferences even when the parent channel is unsubscribed. Users won't receive messages from these types while the channel remains unsubscribed, but their pr

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "code": "Success",
    "msg": "example",
    "params": {}
  }
}

Update user

Update user data.

Inputs

CreateNewFieldscreateNewFieldstrue/false
Whether new fields should be ingested and added to the schema. Defaults to project's setting to allow or drop unrecognized fields.
DataFieldsdataFieldsobject
Data to store on the user profile identified by userId or email.
Emailemailtext
An email address that identifies a user profile in Iterable. Provide an email or a userId (but not both), depending on how your project identifies users.
MergeNestedObjectsmergeNestedObjectstrue/false
Merge top-level objects instead of overwriting them. Defaults to false. For example, if a user profile has data {"mySettings":{"mobile":true}} and the request has data {"mySettings":{"email":true}}, merging results in {"mySettings":{"mobile":true,"email":true}}.
PreferUserIdpreferUserIdtrue/false
Whether or not a new user should be created if the request includes a userId that doesn't yet exist in the Iterable project. Defaults to false. Only respected in API calls for email-based projects.
User IDuserIdtext
A user ID that identifies a user profile in Iterable. Provide an email or a userId (but not both), depending on how your project identifies users.

Outputs

dataobject
The result returned by Iterable.
Example output
{
  "data": {
    "code": "Success",
    "msg": "example",
    "params": {}
  }
}

On this page