API overview and sample payloads

This article includes a complete overview of each Iterable API type, how to use them, sample requests, and best practices.

When submitting an API call, you can enter your API key either in the URI or in the headers.

# Table of contents

# Where are my API keys?

Find an Iterable API key by navigating to Integrations > API Keys:

# Where are Iterable's API docs?

You can add users into Iterable, update users, send events, access data, create campaigns, and much more with Iterable's APIs.

To view Iterable's API documentation, navigate to Help > API Documentation.

You will see a list of our APIs with different functions.

You can also send sample requests on this page.

# Where do I put my API key in the request?

The base URI is https://api.iterable.com.

You can put the API key directly in the query string, using api_key or apiKey. An example of an API call for the events track API would be:

https://api.iterable.com/api/events/track?apiKey=YOUR_API_KEY

You can also place your API key in the header. The name of the header field for the API key is Api_Key or Api-Key.

In our API docs, before entering your JSON payload, you'll need to authorize the API key in the Authentication Header section on the upper-left hand corner of the page. If you enter the JSON payload first, once you authorize the key, the JSON payload will be erased and need to be re-entered.

# API response bodies

Iterable may occasionally add fields to API response bodies as needed. Be sure that any dependencies you have on these APIs will not break if and when these new fields are added.

Iterable will not rename or remove existing, documented fields from an API response body without prior communication.

# List APIs

# Add subscribers to list

POST /api/lists/subscribe

This is used to add a subscriber to an existing static list.

Sample JSON request body:

{
    "listId": 123,
    "subscribers": [
        {
            "email": "docs@iterable.com",
            "dataFields": {
                "firstName": "Sherry",
                "hasCat": true
            },
            "userId": "1"
        }
    ]
} 

Optional fields: dataFields, userId

# Delete static list

DELETE /api/lists/{listId}

This is used to delete a list. All users who are part of the deleted list will have the list removed from their profile.

Sample request:

https://api.iterable.com:443/api/lists/21398?api_key=YOUR_API_KEY

# Remove users from list

POST /api/lists/unsubscribe

This is used to remove one or more subscribers from an existing static list.

Sample JSON request body:

{
    "listId": 1,
    "subscribers": [
        {
            "email": "docs@iterable.com"
        },
        {
            "email": "support@iterable.com"
        }
    ],
    "campaignId": 123,
    "channelUnsubscribe": false
}

Optional fields: campaignId, channelUnsubscribe

# Get users in list

GET /api/lists/getUsers

Returns a string of all the users who are on a list. Works for both static and dynamic lists

Sample:

https://api.iterable.com:443/api/lists/getUsers?listId=21401&api_key=YOUR_API_KEY

# Get lists from project

GET /api/lists

This will return all the static lists in a project.

Sample:

https://api.iterable.com:443/api/lists?api_key=YOUR_API_KEY

# Create static list

POST /api/lists

Use this to create a new, empty, standard list with the specified name. Upon creation of the new list, it will return the list ID.

Sample JSON request body:

{
    "name": "exampleListName"
}

# Subscription APIs

# Subscribe a user to a single channel, message type, or list

PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}

• For subscriptionGroup, provide one of the following values:

  • messageChannel
  • messageType
  • emailList

• For subscriptionGroupId, provide the ID of the message channel, message type, or email list to which you are subscribing the user.

• For userEmail, provide the email address of the user for which you'd like to create a subscription.

• This is an asynchronous API. It returns 202 on success.

• For example, the following call subscribes user docs@iterable.com to message type 12345:

  PATCH https://api.iterable.com/api/subscriptions/messageType/12345/user/docs%40iterable.com&api_key=YOUR_API_KEY

# Unsubscribe a user from a single channel, message type, or list

DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}

• For subscriptionGroup, provide one of the following values:

  • messageChannel
  • messageType
  • emailList

• For subscriptionGroupId, provide the ID of the message channel, message type, or email list from which you are unsubscribing the user.

• For userEmail, provide the email address of the user from which you are unsubscribing the user.

• This is an asynchronous API. It returns 202 on success.

• For example, the following call unsubscribes user docs@iterable.com to message type 12345:

  DELETE https://api.iterable.com/api/subscriptions/messageType/12345/user/docs%40iterable.com&api_key=YOUR_API_KEY

# Subscribe or unsubscribe multiple users to the same channel, message type, or list

PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe

• To subscribe multiple users to the same channel, message type, or list, use action=subscribe (as shown in the above URL). To unsubscribe, use action=unsubscribe.

• For subscriptionGroup, provide one of the following values:

  • messageChannel
  • messageType
  • emailList

• For subscriptionGroupId, provide the ID of the message channel, message type, or email list to which you are subscribing the users.

• For the JSON request body, provide a users array containing the email addresses of the users to subscribe.

• This is an asynchronous API. It returns 202 on success.

• For example, the following request subscribes docs@iterable.com and support@iterable.com to message type 12345:

  PUT https://api.iterable.com/api/subscriptions/messageType/12345?action=subscribe&api_key=YOUR_API_KEY

  Request body:

  {
     "users": [ 
        "docs@iterable.com",
        "support@iterable.com"
     ]
  }
  

# Events APIs

# Get events associated with a user

GET /api/events/{email}

Use this to receive events associated with a user profile. This will include custom events and standard Iterable events like sent an email, opened email, and clicked a link. The default value for limit is 30; if no override is set, the user's last 30 events will be returned.

Sample:

https://api.iterable.com:443/api/events/jeremy%40iterable.com?api_key=YOUR_API_KEY

Sample JSON response:

{
    "events": [
        {
            "contentId": 330397,
            "recurringCampaignId": 12345,
            "email": "jeremy@iterable.com",
            "createdAt": "2016-10-04 00:54:00 +00:00",
            "campaignId": 67890,
            "templateId": 11111,
            "messageId": "1234example9876",
            "eventType": "emailSend"
        },
        {
            "contentId": 329261,
            "recurringCampaignId": 12345,
            "email": "jeremy@iterable.com",
            "createdAt": "2016-09-30 19:50:00 +00:00",
            "campaignId": 67890,
            "templateId": 22222,
            "messageId": "9876example1234",
            "eventType": "emailSend"
        }
    ]
}

# Track event

POST /api/events/track

Use this to send custom events, such as user logins, signups, and app opens to Iterable. These events can then be used to trigger workflows or for custom conversion tracking in campaigns. Data fields in custom event calls can be used to populate merge parameters in templates. You can also segment on these events in the user profile. Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence.

An optional string id parameter may be passed as one of the top-level parameters. If an event exists with that id, the event will be updated. If no id is specified, a new id will automatically be generated and returned.

Sample JSON request body:

{
    "email": "docs@iterable.com",
    "eventName": "startedMembership",
    "id": "12345",
    "dataFields": {
        "source": "facebook",
        "membershipType": "monthly"
    },
    "userId": "1",
    "campaignId": 123,
    "templateId": 123
}

Optional fields: email or userId (but not both), id, createdAt, dataFields, campaignId, templateId

# Bulk track events

POST /api/events/trackBulk

Tracks multiple custom events. Either email or userId is required for each event. Empty event names are not allowed.

Events are created asynchronously and processed separately from the non-bulk event tracking endpoint. Thus, if you need to make sure events are tracked in order, send all of them to the same endpoint (either bulk or non-bulk).

Limitations:

• Rate limit: 10 requests/second, per project.
• An Iterable project can contain up to 8,000 unique custom event field names. If the same field name is used on various custom events that have different eventName values, it counts multiple times against this limit.
• Types of data fields must match the types sent in previous requests, across all data fields in the project (for the same event name).
• Bulk events are processed separately from regular event track endpoint.
• There's a 4MB limit for the request's JSON body (about 1000 events).
• Fields per event are the same as for single event in regular track event endpoint.

Sample JSON request body:

{
    "events": [
        {
            "email": "docs@iterable.com",
            "eventName": "startedMembership",
            "id": "12345",
            "dataFields": {
                "source": "facebook",
                "membershipType": "monthly"
            },
            "userId": "1",
            "campaignId": 123,
            "templateId": 123
        },
        {
            "email": "brad@iterable.com",
            "eventName": "quizCompleted",
            "id": "45678",
            "dataFields": {
                "score": 9
            }
        }
    ]
}

Optional fields: email or userId (but not both), id, createdAt, dataFields, campaignId, templateId

# Track push open

POST /api/events/trackPushOpen

Use this to track a mobile push notification open. Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence. Include the campaignId in the call and it will attribute the open to the Iterable campaign that sent the notification. Learn more about sending push notifications with Iterable.

Sample JSON request body:

{
    "email": "jeremy@iterable.com",
    "userId": "2",
    "campaignId": 12345,
    "templateId": 67890,
    "messageId": "01234567890",
    "dataFields": {
        "openedMostRecentPush": true
    }
}

Optional fields: email, userId, campaignId, templateId, messageId, dataFields

# Track in-app message click

POST /api/events/trackInAppClick

Use this to track an in-app message click. Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence. Generates an inAppClick event.

Sample JSON request body:

{
    "email": "chris@iterable.com",
    "userId": "123",
    "messageId": "01234567890"
}

Optional fields: email, userId

# Delete or consume in-app message

To track the deletion of an in-app message, call the following API, which generates an inAppDelete event.

To consume an in-app message (delete it from the server queue without generating an inAppDelete event), call this same API but specify only the email or userId and messageId parameters in the request body.

POST /api/events/inAppConsume

Request body:

{
    "email": "string",
    "userId": "string",
    "messageId": "string",
    "deleteAction": "string", // inbox-swipe or delete-button
    "messageContext": {
        "location": "string", // inbox or in-app (where this event happened)
        "saveToInbox" true, // boolean
        "silentInbox": false // boolean
    }
    "deviceInfo": {
        "deviceId": "string", // Unique identifier
        "platform": "string", // iOS or Android
        "appPackageName": "string"
    }
}

Optional fields: specify email or userId, but not both.

# Track in-app message open

POST /api/events/trackInAppOpen

Use this to track an in-app message open. Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence. Generates an inAppOpen event.

Sample JSON request body:

{
    "email": "chris@iterable.com",
    "userId": "123",
    "messageId": "01234567890"
}

Optional fields: email, userId

# User APIs

# Bulk update subscriptions

POST /api/users/bulkUpdateSubscriptions

Updates one or more users' subscription preferences. Include campaignId and/or templateId to attribute unsubscribes to campaigns and templates. Either email or userId is required.

Sample JSON request body:

{
    "updateSubscriptionsRequests": [
        {
            "email": "support@iterable.com",
            "userId": "0192837821",
            "unsubscribedChannelIds": [
                12345,
                23456
            ],
            "unsubscribedMessageTypeIds": [
                65432
            ],
            "campaignId": 34567,
            "templateId": 456789
        },
        {
            "email": "docs@iterable.com",
            "userId": "2131238573",
            "unsubscribedChannelIds": [
                12345
            ],
            "campaignId": 34567,
            "templateId": 456789
        }
    ]
}

Optional fields: email, userId, unsubsubscribedChannelIds, unsubscribedMessageTypeIds, campaignId, templateId

# Update a user's email

POST /api/users/updateEmail

Updates a user's email address. If the new email already exists in Iterable, an error will occur.

Sample JSON request body:

{
    "currentEmail": "docs.old@iterable.com",
    "userId": "0192837821",
    "newEmail": "docs.new@iterable.com"
}

Optional fields: currentEmail, userId

# Bulk update

POST /api/users/bulkUpdate

Updates user profiles for one or more users.

Sample JSON Body:

{
    "users": [
        {
            "email": "docs@iterable.com",
            "userId": "0192837821",
            "dataFields": {
                "favoriteColor": "orange"
            }
        },
        {
            "email": "support@iterable.com",
            "userId": "9281928374",
            "dataFields": {
                "favoriteColor": "blue"
            }
        },
        {
            "userId": "2394029394",
            "preferUserId": true,
            "dataFields": {
                "favoriteColor": "red",
            }
        }

    ]
}

Optional fields: email, userId, preferUserId, mergeNestedObjects

# Register device token

POST /api/users/registerDeviceToken

Registers a mobile device token to enable push notifications. Either email or userId must be passed in to identify the user. If both are passed in,email takes precedence. Learn more about sending push notifications with Iterable.

Sample JSON request body:

{
    "email": "jeremy@iterable.com",
    "device": {
        "token": "sampleToken123",
        "platform": "APNS",
        "applicationName": "Pizza Tracker",
        "dataFields": {
            "phoneType": "iPhone 6 plus"
        }
    },
    "userId": "2"
}

Optional fields: email, dataFields, userId

# Update user subscriptions

POST /api/users/updateSubscriptions

Updates a user's subscription settings with new settings.

Sample JSON request body:

{
    "email": "docs@iterable.com",
    "userId": "0192837821",
    "emailListIds": [
        5,
        6,
        7
    ],
    "unsubscribedChannelIds": [
        100
    ],
    "unsubscribedMessageTypeIds": [
        100
    ],
    "campaignId": 123,
    "templateId": 123
}

Optional fields: email, userId, emailListIds, unsubscribedChannelIds, unsubscribedMessageTypeIds, campaignId, templateId

# Get user fields

GET /api/users/getFields

Gets just the fields on users' profiles.

Sample:

https://api.iterable.com:443/api/users/getFields?api_key=YOUR_API_KEY

Sample JSON response:

{
    "fields": {
        "phoneNumber": "string",
        "email": "string",
        "lastName": "string",
        "firstName": "string",
        "signupDate": "date",
        "profileUpdatedAt": "date",
        "signupSource": "string"
    }
}

# Delete a user

DELETE /api/users/{email}

Sample:

https://api.iterable.com:443/api/users/jeremy%40iterable.com?api_key=YOUR_API_KEY

# Get a user

GET /api/users/{email}

Gets user's data fields and info.

Sample:

https://api.iterable.com:443/api/users/jeremy%40iterable.com?api_key=YOUR_API_KEY

# Delete a user by userID

DELETE /api/users/byUserId/{userId}

Delete a user using userId instead of email.

Sample:

https://api.iterable.com:443/api/users/byUserId/[USER_ID]?api_key=YOUR_API_KEY

# Get a user by userId

GET /api/users/byUserId/{userId}

Gets user's data fields and info. Uses userId instead of the user's email.

Sample:

https://api.iterable.com:443/api/users/byUserId?userId=[USER_ID]&api_key=YOUR_API_KEY

# User update

POST /api/users/update

Updates a user profile with new data fields. Missing fields are not deleted and new data is merged.

Sample JSON body:

{
    "email": "docs@iterable.com",
    "dataFields": {
        "catName": "Jimmy"
    },
    "userId": "1",
    "mergeNestedObjects": true
}

Optional fields: email, userId, mergeNestedObjects

# Get sent messages

GET /api/users/getSentMessages

Returns a list of sent messages to a user within a certain time period. Includes the messageId, campaignId, templateId, and createdAt data. Does not include the body of the message.

campaignId, excludeBlastCampaigns, startDateTime, and endDateTime are all optional.

Sample:

https://api.iterable.com:443/api/users/getSentMessages?email=jeremy%40iterable.com&limit=2&campaignId=123&excludeBlastCampaigns=false&startDateTime=2016-10-01%2021%3A00%3A27%20%2B00%3A00&endDateTime=2016-10-29%2000%3A54%3A00%20%2B00%3A00&api_key=YOUR_API_KEY

Sample JSON response:

{
    "messages": [
        {
            "messageId": "9876example4321",
            "campaignId": 123,
            "templateId": 456,
            "createdAt": "2016-10-04 00:54:00 +00:00"
        },
        {
            "messageId": "1234example5678",
            "campaignId": 321,
            "templateId": 654,
            "createdAt": "2016-09-30 19:50:00 +00:00"
        }
    ]
}

# Disable device

POST /api/users/disableDevice

Disables device. Prevents it from receiving push notifications. Must include the device token.

If the token exists on multiple user profiles, including email will disable the token for that one email address only. If email is not included, the token will be disabled from all user profiles. The same is true for including or not including 'userId'.

Sample JSON request body:

{
    "token": "sampleToken123",
    "email": "jeremy@iterable.com",
    "userId": "2"
 }

Optional fields: email, userId

# Push APIs

# Target user

POST /api/push/target

Sends a triggered push notification to a specific user. Request data fields will override existing user profile data fields. Campaign must be set up in Iterable beforehand. If sendAt field is not included, message will be sent immediately.

Sample JSON request body:

{
    "campaignId": 13770,
    "recipientEmail": "docs@iterable.com",
    "dataFields": {
        "newUser": "FALSE"
    },
    "sendAt": "2016-08-25 23:25:00 +00:00"
}

Optional fields: dataFields, sendAt

# In-app message APIs

# Get in-app messages for user

GET /api/inApp/getMessages

Get in-app mobile messages that should be displayed to a user.

Sample request:

https://api.iterable.com:443/api/inApp/getMessages?email=chris%40iterable.com&userId=1234&count=123&api_key=YOUR_API_KEY

# Cancel in-app message to user

POST /api/inApp/cancel

Indicate that an in-app message should not be delivered to a user and remove it from the server's message queue.

Sample JSON body:

{
    "email": "docs@iterable.com",
    "campaignId": 13770
}

# Send in-app message to user

GET /api/inApp/target

Sends in-app message to a specific user. Request data fields will override existing user profile data fields. Campaign must be set up in Iterable beforehand. If sendAt field is not included, message will be sent immediately.

Sample JSON body:

{
    "campaignId": 13770,
    "recipientEmail": "docs@iterable.com",
    "dataFields": {
       "newUser": "FALSE"
    },
    "sendAt": "2016-08-25 23:25:00 +00:00"
}

Optional fields: dataFields, sendAt

# Experiment APIs

# Get experiment metrics

GET /api/experiments/metrics

Get metrics for experiments(s). Note that we currently only export email experiment metrics.

Sample:

https://api.iterable.com:443/api/experiments/metrics?experimentId=12345&campaignId=23456&startDateTime=2017-06-01&endDateTime=2017-07-01&api_key=YOUR_API_KEY

# SMS APIs

# Target user

POST /api/sms/target

Sends SMS to a specific user. Request data fields will override existing user profile data fields. Campaign must be set up in Iterable beforehand. If sendAt field is not included, message will be sent immediately.

Sample JSON request body:

{
    "campaignId": 13770,
    "recipientEmail": "docs@iterable.com",
    "dataFields": {
       "newUser": "FALSE"
    },
    "sendAt": "2016-08-25 23:25:00 +00:00"
}

Optional fields: dataFields, sendAt

# Message type APIs

# Get message types

GET /api/messageTypes

Lists all message types for that project.

Sample JSON response:

{
    "messageTypes": [
        {
            "id": 3868,
            "name": "Push Marketing Message",
            "channelId": 3422
        },
        {
            "id": 3867,
            "name": "Transactional Message",
            "channelId": 3421
        },
        {
            "id": 3866,
            "name": "Marketing Message",
            "channelId": 3420
        }
    ]
}

# Channel APIs

# Get channels

GET /api/channels

Lists all channels for that project.

Sample JSON response:

{
    "channels": [
        {
            "id": 3422,
            "name": "Push Marketing Channel",
            "channelType": "Marketing",
            "messageMedium": "Push"
        },
        {
            "id": 3421,
            "name": "Transactional Channel",
            "channelType": "Transactional",
            "messageMedium": "Email"
        },
        {
            "id": 3420,
            "name": "Marketing Channel",
            "channelType": "Marketing",
            "messageMedium": "Email"
        }
    ]
}

# Template APIs

# Update SMS template

POST /api/templates/sms/update

Updates a specific SMS template. Most fields are optional. Include the fields you wish to update.

Sample JSON request body:

{
    "templateId": 123,
    "name": "My SMS Title",
    "message": "I like animals.",
    "locale": "fr",
    "messageTypeId": 531
}

Optional fields: name, message, locale, messageTypeId

# Get templates in a project

GET /api/templates

Gets info for the templates in a project. Includes the templateId, creation and modification times, the name of the template, the creator of the template, and the message type used.

Sample:

https://api.iterable.com:443/api/templates?templateType=Base&messageMedium=Email&api_key=YOUR_API_KEY

Sample JSON response:

{
    "templates": [
        {
            "templateId": 86596,
            "createdAt": 1473368899828,
            "updatedAt": 1473370111852,
            "name": "Regular editor",
            "creatorUserId": "jeremy@iterable.com",
            "messageTypeId": 3867
        },
        {
            "templateId": 68178,
            "createdAt": 1466810056349,
            "updatedAt": 1470431713441,
            "name": "Photography Welcome Message",
            "creatorUserId": "jeremy@iterable.com",
            "messageTypeId": 3866
        }
    ]
}

# Update push template

POST /api/templates/push/update

Updates a specific push template. Most fields are optional. Include the fields you wish to update.

Sample JSON request body:

{
    "templateId": 0,
    "name": "string",
    "title": "string",
    "message": "string",
    "payload": {},
    "badge": "string",
    "locale": {
        "name": "string"
    },
    "messageTypeId": 0,
    "sound": "string",
    "deeplink": {
        "ios": "string",
        "android": "string"
    },
    "clientTemplateId": "string",
    "campaignId": 0
}

Optional fields: name, title, message, payload, badge, locale, messageTypeId, sound, deepLink, clientTemplateId, campaignId

# Get an email template

GET /api/templates/email/get

Get an email template's information and HTML.

Sample JSON response:

{
    "templateId": 86596,
    "name": "My name of template",
    "fromName": "Customer Success",
    "fromEmail": "jeremy@iterable.com",
    "replyToEmail": "jeremy+replyTo@iterable.com",
    "subject": "My Subject of message",
    "preheaderText": "preheader message here",
    "ccEmails": [],
    "bccEmails": [],
    "html": "<html>\n\n<head>\n<title></title>\n</head>\n\n<body>\n <p>\n {{userPropertyParameter}}\n </p>\n</body>\n\n</html>",
    "plainText": "Optional plain text message",
    "cacheDataFeed": false,
    "mergeDataFeedContext": true,
    "messageTypeId": 3867,
    "creatorUserId": "jeremy@iterable.com"
}

# Upsert an SMS template

POST /api/templates/sms/upsert

Creates a new template if one does not exist, or updates all templates with the specified client template id.

Sample JSON request body:

{
    "clientTemplateId": 112233,
    "name": "SMS Test",
    "message": "Hello There!",
    "locale": "en",
    "messageTypeId": "1234"
} 

Optional fields: name, message, locale

# Get an SMS template

GET /api/templates/sms/get

Get an SMS template information and message string.

Sample JSON response:

{
    "templateId": 100692,
    "name": "SMS testing",
    "message": "Here is example message",
    "messageTypeId": 4769
}

# Get a push template

GET /api/templates/push/get

Get a push template information and message string.

Sample JSON response:

{
    "templateId": 0,
    "createdAt": "2019-02-07T07:30:56.741Z",
    "updatedAt": "2019-02-07T07:30:56.741Z",
    "name": "string",
    "title": "string",
    "message": "string",
    "payload": {},
    "badge": "string",
    "locale": {
        "name": "string"
    },
    "messageTypeId": 0,
    "sound": "string",
    "deeplink": {
        "ios": "string",
        "android": "string"
    },
    "clientTemplateId": "string",
    "campaignId": 0
}

# Get an email template from a client template id

GET /api/templates/getByClientTemplateId

Get an array of template ids that match a client template id. If the client has set a clientTemplateId on any email template(s), then this call will return those templates.

# Update email template

POST /api/templates/email/update

Updates a specific email template. Only fields specified will be updated.

Template before update:

Sample JSON request body:

{
    "templateId": 53081,
    "name": "Lots of Cats",
    "fromName": "Felicia the Cat",
    "fromEmail": "lindsey+replyto@iterable.com",
    "replyToEmail": "lindsey+replyto@iterable.com",
    "subject": "Rank These Cats",
    "preheaderText": "10 out of 10!",
    "html": "<html><body><p>So many cats!</p></body></html>"
 }

Optional fields: name, fromName, fromEmail, replyToEmail, subject, preheaderText, html

Template after update:

# Upsert an email template

POST /api/templates/email/upsert

Creates a new template if one does not exist, or updates all templates with the specified client template id.

Sample JSON request body:

{
    "clientTemplateId": 112233,
    "name": "Lots of Cats",
    "fromName": "Felicia the Cat",
    "fromEmail": "Jeremy@iterable.com",
    "replyToEmail": "Jeremy+replyTo@iterable.com",
    "subject": "Rank These Cats",
    "preheaderText": "10 out of 10!",
    "html": "<html><body><p>So many cats!</p></body></html>"
}

Optional fields: name, fromName, fromEmail, replyToEmail, subject, preheaderText, html

# Upsert an push template

POST /api/templates/push/upsert

Creates a new template if one does not exist, or updates all templates with the specified client template id.

Sample JSON request body:

{
    "clientTemplateId": 112233,
    "name": "Lots of Cats",
    "messages": "Rank These Cats",
}

Optional fields: name, messages

# Campaign APIs

# Create campaign

POST /api/campaigns/create

Creates and schedules a blast campaign up to two weeks in advance. The campaign will have a new template with a new template id. If the sendAt field is not included, message will be sent immediately.

Sample JSON request body:

{
    "name": "Sample API Blast Campaign",
    "listIds": [
        5925,
        6094
    ],
    "templateId": 28533,
    "suppressionListIds": [
        6095
    ],
    "sendAt": "2015-09-15 00:00:00"
}

Optional fields: listIds, suppresionListIds, sendAt

# Get campaigns

GET /api/campaigns

Gets info such as id, createdAt, name, templateId, etc. from campaigns.

Sample JSON response:

{
    "campaigns": [
        {
            "id": 59530,
            "createdAt": 1475452500507,
            "updatedAt": 1475452500591,
            "startAt": 1475535300000,
            "endedAt": 1475542440016,
            "name": "Recurring | 2016-10-02 | Pre-Make a campaign ahead of time",
            "templateId": 93661,
            "createdByUserId": "jeremy@iterable.com",
            "campaignState": "Finished",
            "listIds": [
                16182
            ],
            "suppressionListIds": [],
            "sendSize": 3
        },
        {
            "id": 59355,
            "createdAt": 1475265000217,
            "updatedAt": 1475265000276,
            "startAt": 1475265000274,
            "endedAt": 1475265000320,
            "name": "Recurring | 2016-09-30 | Recurring - Jeremy's List",
            "templateId": 93419,
            "createdByUserId": "jeremy@iterable.com",
            "campaignState": "Finished",
            "listIds": [
                14007
            ],
            "suppressionListIds": [],
            "sendSize": 3
        }
    ]
}

# Get child campaigns

GET /api/campaigns/recurring/{id}/childCampaigns

Get details for campaigns generated by a recurring campaign.

Sample:

https://api.iterable.com:443/api/campaigns/recurring/12345/childCampaigns&api_key=YOUR_API_KEY

# Campaign metrics

GET /api/campaigns/metrics

Gets analytic info such as id, bounces, clicks, conversions, purchases, etc. from a campaign. A start and end date can be added to select the desired range of analytics.

Sample CSV response:

id,bounces,clicks,conversions,opens,purchases,pushBounces,pushOpens,pushSent,pushUninstalls,revenue,sent,smsBounces,smsReceived,smsSent,spams,totalClicks,totalOpens,totalPushOpens,unsubs 
59355,0,0,,0,0,,,,,0.0,3,,,,0,0,0,,0

# Commerce APIs

# Update cart

POST /api/commerce/updateCart

Updates shoppingCartItems field on the user profile. Fields in bold are required.

Sample JSON request body:

{
    "user": {
        "email": "docs@iterable.com",
        "dataFields": {
            "currentCartTotal": 34
        },
        "userId": "1",
        "mergeNestedObjects": true
    },
    "items": [
        {
            "id": "2",
            "sku": "4",
            "name": "Iterable T-shirt",
            "description": "100% cotton shirt. Show how much you love your favorite marketing automation platform!",
            "categories": [
                "clothing",
                "swag"
            ],
            "price": 20.50,
            "quantity": 1,
            "imageUrl": "http://static.iterable.com/iterable/15-10-03-iterableshirt.png",
            "url": "iterable.com"
        },
        {
            "id": "3",
            "sku": "5",
            "name": "Macadamia Nuts",
            "description": "Full of healthy fats! Made in Hawaii.",
            "categories": [
                "food"
            ],
            "price": 5.50,
            "quantity": 2,
            "imageUrl": "https://nuts.com/images/auto/510x340/assets/4d57de389a2f6d59.jpg",
            "url": "iterable.com"
        }
    ]
}

# Track purchase

POST /api/commerce/trackPurchase

Tracks when a user makes a purchase. Also clears shoppingCartItems on the user profile. Adding in the campaignId will attribute the purchase to specific Iterable campaign. Fields in bold are required.

An optional string id parameter may be passed as one of the top-level parameters. If a purchase event exists with that id, the event will be updated. If no id is specified, a new id will automatically be generated and returned.

Sample JSON request body:

{
    "user": {
        "email": "docs@iterable.com",
        "dataFields": {
            "totalPurchases": 5
        },
        "userId": "1"
    },
    "items": [
        {
            "id": "1",
            "sku": "1",
            "name": "Iterable Stickers",
            "description": "Put these stickers anywhere and everywhere!",
            "categories": [
                "stickers",
                "novelty"
            ],
            "price": 5.50,
            "quantity": 2,
            "imageUrl": "http://static.iterable.com/iterable-demo-v1/15-03-04-Iterable_stickers.jpg",
            "url": "iterable.com"
        }
    ],
    "campaignId": 14348,
    "templateId": 29592,
    "total": 11,
    "dataFields": {
        "shippingAddress1": "360 3rd Street",
        "shippingAddress2": "Suite 675",
        "city": "San Francisco",
        "state": "CA",
        "zip": 94107
    }
}

# Email APIs

# Target user

POST /api/email/target

Sends a triggered email campaign to specified email address. If sendAt field is not included, message will be sent immediately. The JSON passed in the dataFields section will be indexed on the emailSend event as transactionalData.

Sample JSON request body:

{
    "campaignId": 13594,
    "recipientEmail": "docs@iterable.com",
    "dataFields": {
        "customParam": "paramValue"
    },
    "sendAt": "2015-08-31 22:00:00 +00:00"
}

# View in browser

GET /api/email/viewInBrowser

View a copy of a previously sent email. Must include both a user's email address and the message id of the sent email.

Sample:

https://api.iterable.com:443/api/email/viewInBrowser?email=jeremy%40iterable.com&messageId=340c333dea5e43cea6de24170d8a81c8&api_key=YOUR_API_KEY

# Export APIs

# Export data (CSV)

GET /api/export/data.csv

Exports different types of data (purchases, user created, email sends, email opens, etc.) in CSV format. When the call is made, a string is returned as a .csv file. This file is then available for download.

# Export data (JSON)

GET /api/export/data.json

Exports different types of data (purchases, user created, email sends, email opens, etc) in JSON format.

Sample JSON response:

{
    {
        "contentId": 243307,
        "recurringCampaignId": 41777,
        "email": "exampleEmail@iterable.com",
        "createdAt": "2016-07-08 19:50:00 +00:00",
        "campaignId": 43521,
        "templateId": 71213
    }
    {
        "contentId": 242909,
        "email": "exampleEmail@iterable.com",
        "createdAt": "2016-07-08 16:58:19 +00:00",
        "campaignId": 43444,
        "templateId": 71115
    }
    {
        "contentId": 243307,
        "recurringCampaignId": 41777,
        "email": "exampleEmail+1@iterable.com",
        "createdAt": "2016-07-08 19:50:00 +00:00",
        "campaignId": 43521,
        "templateId": 71213
    }
    {
        "contentId": 243307,
        "recurringCampaignId": 41777,
        "email": "exampleEmail@iterable.com",
        "createdAt": "2016-07-08 19:50:00 +00:00",
        "campaignId": 43521,
        "templateId": 71213
    }
}

# Workflow APIs

# Trigger workflow

POST /api/workflows/triggerWorkflow

Triggers a workflow for a single user and/or all users on a list. Works for both standard and dynamic lists.

Sample request body (JSON):

{
    "email": "jeremy@iterable.com",
    "workflowId": 2765,
    "listId": 6094,
    "dataFields": {
        "signupSource": "google",
        "optIn": true
    }
}

# Catalog APIs

# Create a catalog

POST /api/catalogs/{catalogName}

Creates a new catalog in the project associated with the API key. Each catalog in an Iterable project must have a unique name that is no longer than 255 characters and contains only letters, numbers, and dashes (no spaces, underscores, or other special characters).

Example:

• POST https://api.iterable.com/api/catalogs/Trucks?api_key=YOUR_API_KEY

• Response body (JSON):

  {
      "msg": "",
      "code": "Success",
      "params": {
          "id": 740,
          "name": "Trucks",
          "url": "/api/catalogs/Trucks?api_key=YOUR_API_KEY"
      }
  }
  

• On success, this API returns HTTP status code 201.

# Get catalog names

GET /api/catalogs

Lists the names of all catalogs in the project associated with an API key.

Example:

• GET https://api.iterable.com/api/catalogs?api_key=YOUR_API_KEY

• Paging:

  • Use page and pageSize in the query string to specify a page number and page size. For example:

    GET https://api.iterable.com/api/catalogs?api_key=YOUR_API_KEY&page=3&pageSize=10

  • When passing these parameters, the API will return previousPageUrl and nextPageUrl values (as applicable). Use these to load more data.

  • If you specify a page and pageSize combination outside the range of available data, the API will return an empty list of catalog names.

• Response body (JSON):

  {
      "msg": "",
      "code": "Success",
      "params": {
          "catalogNames": [
              {
                  "name": "Trucks"
              }
          ],
          "totalCatalogsCount": 1
      }
  }
  

• On success, this API returns HTTP status code 200.

# Delete a catalog

DELETE /api/catalogs/{catalogName}

Deletes a catalog and all its items.

Example:

• DELETE https://api.iterable.com/api/catalogs/Trucks?api_key=YOUR_API_KEY

• Response body (JSON):

  {
      "msg": "Successfully deleted catalog Trucks",
      "code": "Success",
      "params": null
  }
  

• On success, this API returns HTTP status code 200.

# Bulk create catalog items

POST /api/catalogs/{catalogName}/items

Creates up to 1,000 catalog items at a time (each one having a max size of 30kb). This is an asynchronous API; 202 response code indicates that the request has been received and will be processed.

The request body should specify a JSON object with a top-level document key and an associated object. In the document object, each key corresponds to the ID of a catalog item, and the key's associated object contains the catalog item's fields.

Catalog items must have unique IDs (within a catalog). They may contain letters, numbers, and dashes (no spaces, underscores, or other special characters), and must be no longer than 255 characters.

If the catalog already contains an item having the same ID as one provided in the request body, the existing item will be completely overwritten by the item specified in the request body Do not use the period character in catalog item field names.

Example:

• POST https://api.iterable.com/api/catalogs/Trucks/items?api_key=YOUR_API_KEY

• Request headers:

  Content-Type: application/json

• Request body (JSON):

  {
      "documents": {
          "PickupTruckA": {
              "options": [
                  "manual transmission",
                  "sunroof",
                  "premium stereo"
              ],
              "manufactureDate": "2019-01-15",
              "current_location": {
                  "lat": 37.773972,
                  "lon": -122.431297
              },
              "fullLength": 230.25,
              "used": true,
              "price": 35000,
              "previousOwner": {
                  "firstName": "John",
                  "lastName": "Smith"
              }
          },
          "PickupTruckB": {
              "options": [
                  "automatic transmission",
                  "keyless entry"
              ],
              "manufactureDate": "2018-06-12",
              "current_location": {
                  "lat": 39.742043,
                  "lon": -104.991531
              },
              "fullLength": 215.75,
              "used": true,
              "price": 29500,
              "previousOwner": {
                  "firstName": "Jane",
                  "lastName": "Jones"
              }
          }
      }
  }
  

• Response body (JSON):

  {
      "msg": "Request to bulk-upload documents into Trucks processed successfully",
      "code": "Success",
      "params": null
  }
  

• On success, this API returns HTTP status code 202.

# Get the catalog items for a catalog

GET /api/catalogs/{catalogName}/items

Lists all catalog items in a catalog.

Example:

• GET https://api.iterable.com/api/catalogs/Trucks/items?api_key=YOUR_API_KEY

• Paging:

  • Use page and pageSize in the query string to specify a page number and page size. For example:

    GET https://api.iterable.com/api/catalogs/Trucks/items?api_key=YOUR_API_KEY&page=3&pageSize=10

  • When passing these parameters, the API will return previousPageUrl and nextPageUrl values (as applicable). Use these to load more data.

  • If you specify a page and pageSize combination outside the range of available data, the API will return an empty list of catalog names.

• Response body (JSON):

  {
      "msg": "",
      "code": "Success",
      "params": {
          "catalogItemsWithProperties": [
              {
                  "catalogName": "Trucks",
                  "itemId": "PickupTruckB",
                  "size": 242,
                  "lastModified": 1555662886000,
                  "value": {
                      "used": true,
                      "current_location": {
                          "lat": 39.742043,
                          "lon": -104.991531
                      },
                      "price": 29500,
                      "manufactureDate": "2018-06-12",
                      "options": [
                          "automatic transmission",
                          "keyless entry"
                      ],
                      "fullLength": 215.75,
                      "previousOwner": {
                          "firstName": "Jane",
                          "lastName": "Jones"
                      }
                  }
              },
              {
                  "catalogName": "Trucks",
                  "itemId": "PickupTruckA",
                  "size": 251,
                  "lastModified": 1555662886000,
                  "value": {
                      "used": false,
                      "current_location": {
                          "lat": 37.773972,
                          "lon": -122.431297
                      },
                      "price": 35000,
                      "manufactureDate": "2019-01-15",
                      "options": [
                          "manual transmission",
                          "sunroof",
                          "premium stereo"
                      ],
                      "fullLength": 230.25,
                      "previousOwner": {
                          "firstName": "John",
                          "lastName": "Smith"
                      }
                  }
              }
          ],
          "totalItemsCount": 2
      }
  }
  

• On success, this API returns HTTP status code 200.

# Get a specific catalog item

GET /api/catalogs/{catalogName}/items/{itemId}

Gets the details of a specific catalog item.

Example:

• GET https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA?api_key=YOUR_API_KEY

• Response body (JSON):

  {
      "msg": "",
      "code": "Success",
      "params": {
          "catalogName": "Trucks",
          "itemId": "PickupTruckA",
          "size": 251,
          "lastModified": 1555662886000,
          "value": {
              "used": false,
              "current_location": {
                  "lat": 37.773972,
                  "lon": -122.431297
              },
              "price": 35000,
              "manufactureDate": "2019-01-15",
              "options": [
                  "manual transmission",
                  "sunroof",
                  "premium stereo"
              ],
              "fullLength": 230.25,
              "previousOwner": {
                  "firstName": "John",
                  "lastName": "Smith"
              }
          }
      }
  }
  

• On success, this API returns HTTP status code 200.

# Create or replace a catalog item

PUT /api/catalogs/{catalogName}/items/{itemId}

Writes over (or creates) a catalog item with the values found in the request body. Any already-existing fields not included in the request body will be deleted. This is an asynchronous call; 202 response code indicates that the request has been received and will be processed.

If the item specified in the URL does not exist, it will be created.

A catalog item ID may contain letters, numbers, and dashes (no spaces, underscores, or other special characters), must be unique, and can contain no more than 255 characters.

Example:

• PUT https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA?api_key=YOUR_API_KEY

• Request headers:

  Content-Type: application/json

• Request body (JSON):

  {
      "value": {
          "used": false
      }
  }
  

• Response body (JSON):

  {
      "msg": "",
      "code": "Success",
      "params": {
          "catalogName": "Trucks",
          "itemId": "PickupTruckA",
          "url": "/api/catalogs/Trucks/items/PickupTruckA?api_key=YOUR_API_KEY"
      }
  }
  

• On success, this API returns HTTP status code 202.

# Create or update a catalog item

PATCH /api/catalogs/{catalogName}/items/{itemId}

Updates (or creates) a catalog item with the values found in the request body. Any already-existing fields not included in the request body will remain as is. This is an asynchronous call; 202 response code indicates that the request has been received and will be processed.

Example:

• PATCH https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckB?api_key=YOUR_API_KEY

• Request headers:

  Content-Type: application/json

• Request body (JSON):

  {
      "update": {
          "price": 45000
      }
  }
  

  • This request will update the `price field on the catalog item in question, but it will leave all other fields on that catalog item as is.

  • Do not use the period character in catalog item field names.

  • This request will overwrite every one of the fields on PickupTruckA, leaving nothing except the price field (set to 45000).

• Response body (JSON):

  {
      "msg": "",
      "code": "Success",
      "params": {
          "catalogName": "Trucks",
          "itemId": "PickupTruckB",
          "url": "/api/catalogs/Trucks/items/PickupTruckB?api_key=YOUR_API_KEY"
      }
  }
  ``
  
  

• On success, this API returns HTTP status code 202.

# Delete a catalog item

DELETE /api/catalogs/{catalogName}/items/{itemId}

Deletes a single catalog item. This is an asynchronous call; 202 response code indicates that the request has been received and will be processed.

Example:

• DELETE https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA?api_key=YOUR_API_KEY

• Response body (JSON):

  {
      "msg": "Received request to deleted item ID PickupTruckA from catalog Trucks",
      "code": "Success",
      "params": null
  }
  

• On success, this API returns HTTP status code 202.

# Bulk delete catalog items

DELETE /api/catalogs/{catalogName}/items

Deletes multiple catalog items. This is an asynchronous call; 202 response code indicates that the request has been received and will be processed.

Example:

• DELETE https://api.iterable.com/api/catalogs/Trucks/items?api_key=YOUR_API_KEY

• Request headers:

  Content-Type: application/json

• Request body (JSON):

  {
      "itemIds": [
          "PickupTruckA",
          "PickupTruckB"
      ]
  }
  

• Response body (JSON):

  {
      "msg": "Successfully received request to delete 2 items from catalog Trucks",
      "code": "Success",
      "params": null
  }
  

• On success, this API returns HTTP status code 202.

# Get field mappings (data types) for a catalog

GET /api/catalogs/{catalogName}/fieldMappings

Lists the data types assigned to the various fields found in the catalog items in a particular catalog.

Example:

• GET https://api.iterable.com/api/catalogs/Trucks/fieldMappings?api_key=YOUR_API_KEY

• Response body (JSON) — no field types defined:

  {
      "msg": "",
      "code": "Success",
      "params": {
          "definedMappings": {},
          "undefinedFields": [
              "used",
              "current_location",
              "price",
              "manufactureDate",
              "options",
              "fullLength",
              "previousOwner"
          ]
      }
  }
  

• Response body (JSON) — many field types defined:

  {
      "msg": "",
      "code": "Success",
      "params": {
          "definedMappings": {
              "used": "boolean",
              "current_location": "geo_location",
              "price": "long",
              "manufactureDate": "date",
              "options": "string",
              "previousOwner.lastName": "string",
              "previousOwner": "object",
              "previousOwner.firstName": "string",
              "fullLength": "double"
          },
          "undefinedFields": []
      }
  }
  

  • Types include: boolean, date, geo_location, long, double, object, and string

  • previousOwner is an object containing a firstName field and a lastName field. All three fields come back in the definedMappings field if their data types have been assigned.

• On success, this API returns HTTP status code 200.

# Set a catalog's field mappings (data types)

PUT /api/catalogs/{catalogName}/fieldMappings

Sets the data types for the various fields found in the catalog items in a particular catalog.

Example:

• PUT https://api.iterable.com/api/catalogs/Trucks/fieldMappings?api_key=YOUR_API_KEY

• Request headers:

  Content-Type: application/json

• Request body (JSON):

  {
      "mappingsUpdates": [
          {
              "fieldName": "used",
              "fieldType": "boolean"
          },
          {
              "fieldName": "manufactureDate",
              "fieldType": "date"
          },
          {
              "fieldName": "current_location",
              "fieldType": "geo_location"
          },
          {
              "fieldName": "price",
              "fieldType": "long"
          },
          {
              "fieldName": "options",
              "fieldType": "string"
          },
          {
              "fieldName": "fullLength",
              "fieldType": "double"
          },
          {
              "fieldName": "previousOwner",
              "fieldType": "object",
              "children": [
                  {
                      "fieldName": "firstName",
                      "fieldType": "string"
                  },
                  {
                      "fieldName": "lastName",
                      "fieldType": "string"
                  }
              ]
          }
      ]
  }
  

  • previousOwner is an object containing a firstName field and a lastName field. The above request body specifies that previousOwner is an object while its children, firstName and lastName, are strings.

  • It is not possible to define types for nested object fields.

  • Allowed types include: boolean, date, geo_location, long, double, object, and string

  • For a catalog collection to search previously uploaded data containing the newly typed fields (using the API or the web interface), you must re-upload or re-create that data.

• Response body (JSON):

  {
      "msg": "",
      "code": "Success",
      "params": null
  }
  

• On success, this API returns HTTP status code 200.