Iterable
App · 25 actions
Manage users, events and list subscriptions, inspect campaigns and templates, and send email or SMS from Iterable campaigns.
Actions
| Action | What it does |
|---|---|
| Create list | Create a static list. |
| Delete list | Delete a list. |
| Delete user by ID | Delete a user profile by its user ID. |
| Get campaign | Get a campaign. |
| Get campaign metrics | Get metrics for campaigns. |
| Get email template | Get an email template by templateId. |
| Get list size | Get count of users in list. |
| Get user | Get a user by email (query parameter). |
| Get user by id | Get a user by userId (path parameter). |
| List campaigns | List campaign metadata. |
| List channels | Get channels. |
| List journeys | Get journeys (workflows). |
| List lists | Get lists. |
| List message types | List message types. |
| List subscribers | Get users in a list. |
| List templates | Get project templates. |
| List user events | Get user events. |
| List user events by id | Get user events by userId. |
| Send email | Send an email to an email address. |
| Send sms | Send SMS notification to user. |
| Subscribe users | Add subscribers to list. |
| Track event | Track an event. |
| Unsubscribe users | Remove users from a list. |
| Update subscriptions | Update user subscriptions. |
| Update user | Update user data. |
Create list
Create a static list.
Inputs
- Description
descriptiontext - Description.
- Name
nametextRequired - Name.
Outputs
dataobject- The result returned by Iterable.
Example output
{
"data": {
"listId": 1
}
}Delete list
Delete a list.
Inputs
- List
listIdnumberRequired - 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 ID
userIdtextRequired - 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
- ID
idnumberRequired - 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
- Campaign
campaignIdlistRequired - Campaign(s) to export
- StartDateTime
startDateTimedate and time - Export starting from (>=). Accepted formats include YYYY-MM-DD and other ISO 8601 formats.
- EndDateTime
endDateTimedate 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
- TemplateId
templateIdnumberRequired - Template ID
- Locale
localetext - 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
- List
listIdnumberRequired - list id
Outputs
dataobject- The result returned by Iterable.
Example output
{
"data": {}
}Get user
Get a user by email (query parameter).
Inputs
- Email
emailtext
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 ID
userIdtextRequired - userId
Outputs
dataobject- The result returned by Iterable.
Example output
{
"data": {
"user": {
"dataFields": {},
"email": "example",
"userId": "example"
}
}
}List campaigns
List campaign metadata.
Inputs
- Page
pagenumber - Page number (starting at 1).At least 1.
- PageSize
pageSizenumber - Number of results to return per page (defaults to 20, maximum of 1000).
- Sort
sorttext - 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. - CampaignState
campaignStatelist - 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
- Page
pagenumber - Page number (starting at 1).At least 1.
- PageSize
pageSizenumber - Number of results to return per page (defaults to 10, maximum of 50).
- Sort
sorttext - Sort field with optional direction prefix. Use - for descending, + or no prefix for ascending. Examples: -createdAt, +name, idDefault:
id. - State
statelist - 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
- List
listIdnumberRequired - list id
- PreferUserId
preferUserIdtrue/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
- TemplateType
templateTypetext - Only retrieve templates associated with this template typeOne of:
Base,Blast,Triggered,Workflow. - MessageMedium
messageMediumtext - Only retrieve templates associated with this message mediumOne of:
Email,Push,InApp,SMS. - StartDateTime
startDateTimedate and time - Get templates created at or after this date time (yyyy-MM-dd HH:mm:ss [ZZ])
- EndDateTime
endDateTimedate and time - Get templates created before this date time (yyyy-MM-dd HH:mm:ss [ZZ])
- Page
pagenumber - Page number (starting at 1).At least 1. Default:
1. - PageSize
pageSizenumber - Number of results to return per page (defaults to 20, maximum of 1000).Default:
20. - Sort
sorttext - 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
- Email
emailtextRequired - Email of the user whose events you are retrieving.
- Limit
limitnumber - 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 ID
userIdtextRequired - UserId of the user whose events you are retrieving.
- Limit
limitnumber - 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
- AllowRepeatMarketingSends
allowRepeatMarketingSendstrue/false - Allow repeat marketing sends? Defaults to true.
- Campaign
campaignIdnumberRequired - Campaign ID
- DataFields
dataFieldsobject - Fields to merge into email template
- Metadata
metadataobject - Metadata to pass back via webhooks. Not used for rendering
- RecipientEmail
recipientEmailtext - 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.
- RecipientUserId
recipientUserIdtext - 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.
- SendAt
sendAtdate 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
- AllowRepeatMarketingSends
allowRepeatMarketingSendstrue/false - Allow repeat marketing sends? Defaults to true.
- Campaign
campaignIdnumberRequired - Campaign ID
- DataFields
dataFieldsobject - Fields to merge into template
- RecipientEmail
recipientEmailtext - 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.
- RecipientUserId
recipientUserIdtext - 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.
- SendAt
sendAtdate 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
- List
listIdnumberRequired - Listid.
- Subscribers
subscriberslistRequired - Subscribers.
- UpdateExistingUsersOnly
updateExistingUsersOnlytrue/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
- Campaign
campaignIdnumber - Campaign tied to conversion
- CreateNewFields
createNewFieldstrue/false - Whether new fields should be ingested and added to the schema. Defaults to project's setting to allow or drop unrecognized fields.
- CreatedAt
createdAtdate and time - When the event happened. Leave blank to use the time Iterable receives it.
- DataFields
dataFieldsobject - 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.
- Email
emailtext - 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.
- EventName
eventNametextRequired - Name of event
- ID
idtext - 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.
- TemplateId
templateIdnumber - Template id
- User ID
userIdtext - 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
- Campaign
campaignIdnumber - attribute unsubscribe to a campaign
- ChannelUnsubscribe
channelUnsubscribetrue/false - Unsubscribe email from list's associated channel - essentially a global unsubscribe. (default: false)
- List
listIdnumberRequired - Listid.
- Subscribers
subscriberslistRequired - 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
- Campaign
campaignIdnumber - Campaign to attribute unsubscribes
- Email
emailtext - 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.
- EmailListIds
emailListIdslist - Lists that a user is subscribed to
- SubscribedMessageTypeIds
subscribedMessageTypeIdslist - 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.
- TemplateId
templateIdnumber - Template to attribute unsubscribes
- UnsubscribedChannelIds
unsubscribedChannelIdslist - Email channel ids to unsubscribe from
- UnsubscribedMessageTypeIds
unsubscribedMessageTypeIdslist - Individual message type IDs to unsubscribe (does not impact channel subscriptions).
- User ID
userIdtext - 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.
- ValidateChannelAlignment
validateChannelAlignmenttrue/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
- CreateNewFields
createNewFieldstrue/false - Whether new fields should be ingested and added to the schema. Defaults to project's setting to allow or drop unrecognized fields.
- DataFields
dataFieldsobject - Data to store on the user profile identified by userId or email.
- Email
emailtext - 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.
- MergeNestedObjects
mergeNestedObjectstrue/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}}.
- PreferUserId
preferUserIdtrue/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 ID
userIdtext - 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": {}
}
}