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 is my API key?

You can find your API key by navigating to Integrations > API Keys in Iterable's navigation menu.

#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 Explorer, go to Support > API Documentation on the left side menu:

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",
    "buttonIndex": 12345
}

Optional fields: email, userId, buttonIndex

#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",
    "buttonIndex": 12345
}

Optional fields: email, userId, buttonIndex

#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, emailtakes 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 them 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>\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:

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.

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.