Articles in this section

See more

API overview and sample payloads

Avatar
David Rangel
  • Updated
Follow

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:

API Keys navigation item

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.

API Documentation navigation item

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 endpoints

Lists

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": "sherry@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": "sherry@iterable.com"
        },
        {
            "email": "jeremy@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"
}

Events

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. If createdAt field is not included, event will be sent immediately. 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": "sherry@iterable.com",
    "eventName": "startedMembership",
    "id": "12345",
    "dataFields": {
        "source": "facebook",
        "membershipType": "monthly"
    },
    "userId": "1",
    "campaignId": 123,
    "templateId": 123
}

Optional fields: email, id, dataFields, userId, 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.
  • There is a soft limit (default is 8,000) on the number of unique fields a custom event can have.
  • 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": "sherry@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, id, createdAt, dataFields, userId, 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 Iterable push notifications here.

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 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. Learn more about Iterable in-app messages here.

Sample JSON request body:

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

Optional fields: email, userId

Consume an in-app message

POST /api/events/inAppConsume

Either email or userId must be passed in to identify the user. If both are passed in,email takes precedence.

Sample JSON request body:

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

Optional fields: email, userId

Track in-app 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. Learn more about Iterable in-app messages here.

Sample JSON request body:

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

Optional fields: email, userId

Users

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.

NOTE

This endpoint will overwrite existing subscription preferences if fields are set and not null.

Sample JSON request body:

{
    "updateSubscriptionsRequests": [
        {
            "email": "chris@iterable.com",
            "userId": "0192837821",
            "unsubscribedChannelIds": [
                12345,
                23456
            ],
            "unsubscribedMessageTypeIds": [
                65432
            ],
            "campaignId": 34567,
            "templateId": 456789
        },
        {
            "email": "sherry@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": "sherrychao@iterable.com",
    "userId": "0192837821",
    "newEmail": "sherry@iterable.com"
}

Optional fields: currentEmail, userId

NOTES

  • All profile data and events will be migrated to the new email address.
  • Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence.

Bulk update

POST /api/users/bulkUpdate

Updates user profiles for one or more users.

NOTES

  • This endpoint is not recommended for time-sensitive user updates, as there may be a delay before the updates are completely processed due to the potentially high volume of these requests.
  • There is also a limit of up to 4MB or roughly 1000 users per call.
  • Changing emailListIds, unsubscribedChannelIds, messageTypeIds through this endpoint will not generate unsubscribe events.
  • If any of the fields emailListIds, unsubscribedChannelIds and/or messageTypeIds are included for a given profile, then whatever is included in the array will be the preferences set for that profile, regardless of what the preferences were before that. If those fields are not included for a given profile, then no adjustments to preferences will be made for that profile.
  • This endpoint will overwrite existing subscription preferences if fields are not passed in array.
  • Either email or userId is required.
  • To create a new user based on userId instead of email, pass in a userId and set preferUserId to true.

Sample JSON Body:

{
    "users": [
        {
            "email": "sherry@iterable.com",
            "userId": "0192837821",
            "dataFields": {
                "favoriteColor": "orange"
            }
        },
        {
            "email": "jeremy@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 push here.

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.

NOTE

This endpoint will overwrite existing subscription preferences if fields are set and not null. Either email or userId is required.

Sample JSON request body:

{
    "email": "sherry@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}

WARNING

This will completely wipe the user profile, including subscription settings and event history. If the user is re-added, the profile will be completely empty and will be subscribed to everything by default. Deleting a user will also remove their historic campaign metrics as well.

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.

WARNING

This will completely wipe the user profile, including subscription settings and event history. If the user is re-added, the profile will be completely empty and will be subscribed to everything by default.

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.

NOTES

  • Either email or userId is required
  • mergeNestedObjects will merge top level object data instead of overwriting it if set to true (default: false)
  • If user profile has data {"mySettings":{"mobile":true}} and change contact field has data: {"mySettings":{"email":true}}, the resulting merged profile will be: {"mySettings":{"mobile":true,"email":true}}
  • If merge nested objects is set to false then the resulting profile will be overwritten and set to {"mySettings":{"email":true}}

Sample JSON body:

{
    "email": "sherry@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

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": "sherry@iterable.com",
    "dataFields": {
        "newUser": "FALSE"
    },
    "sendAt": "2016-08-25 23:25:00 +00:00"
}

Optional fields: dataFields, sendAt

In-app messages

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

Target 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": "sherry@iterable.com",
    "dataFields": {
       "newUser": "FALSE"
    },
    "sendAt": "2016-08-25 23:25:00 +00:00"
}

Optional fields: dataFields, sendAt

Experiments

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

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": "sherry@iterable.com",
    "dataFields": {
       "newUser": "FALSE"
    },
    "sendAt": "2016-08-25 23:25:00 +00:00"
}

Optional fields: dataFields, sendAt

Message types

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
        }
    ]
}

Channels

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"
        }
    ]
}

Templates

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.

NOTE

Leaving templateType blank in the request will result in base templates only being returned.

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>

<head>
<title></title>
</head>

<body>
 <p>
 {{userPropertyParameter}}
 </p>
</body>

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

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:

Template after update

NOTE

This call will not work on templates made with the Drag-and-Drop Editor.

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

Campaigns

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

Update cart

POST /api/commerce/updateCart

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

NOTE

We recommend casting the required price field as a double instead of a long. To do that, you will need to include a number with a decimal in the first call that you use to cast that field. Use a non-zero decimal value to cast the field as a double (example: 5.55). Otherwise, the field will be cast as a long.

Sample JSON request body:

{
    "user": {
        "email": "sherry@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.

NOTE

As mentioned above, we recommend casting the required price and total fields as doubles instead of longs. To do that, you will need to include a number with a decimal in the first call that you use to cast that field.Use a non-zero decimal value to cast the field as a double (example: 5.55). Otherwise, the field will be cast as a long.

Sample JSON request body:

{
    "user": {
        "email": "sherry@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

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.

NOTE

This is an asynchronous call; a 200 response means that the request has been received, not that the email has been sent.

Sample JSON request body:

{
    "campaignId": 13594,
    "recipientEmail": "sherry@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

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

NOTE

The range field will pull information based off of the profile update field.

Workflows

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 JSON request body:

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

Related articles

Comments

0 comments

Please sign in to leave a comment.