This article describes how to get started using Iterable's API. Additionally, it describes each of Iterable's API endpoints, and links out to API reference docs.
Table of contents
- Changes to fields included in API responses
- TLS 1.2
- Authenticating with Iterable's API
- Base URLs
- API reference docs
- Identifying users
- Campaigns
-
Catalogs
- GET /api/catalogs
- DELETE /api/catalogs/{catalogName}
- POST /api/catalogs/{catalogName}
- DELETE /api/catalogs/{catalogName}/items/{itemId}
- GET /api/catalogs/{catalogName}/items/{itemId}
- PATCH /api/catalogs/{catalogName}/items/{itemId}
- PUT /api/catalogs/{catalogName}/items/{itemId}
- DELETE /api/catalogs/{catalogName}/items
- GET /api/catalogs/{catalogName}/items
- POST /api/catalogs/{catalogName}/items
- GET /api/catalogs/{catalogName}/fieldMappings
- PUT /api/catalogs/{catalogName}/fieldMappings
- Channels
- Commerce
-
Events
- POST /api/events/inAppConsume
- POST /api/events/trackInAppClick
- POST /api/events/trackInAppClose
- POST /api/events/trackInAppDelivery
- POST /api/events/trackInAppOpen
- POST /api/events/track
- POST /api/events/trackWebPushClick
- POST /api/events/trackPushOpen
- GET /api/events/{email}
- GET /api/events/byUserId/{userId}
- POST /api/events/trackBulk
- Experiments
- Export
- In-app messages
- Web in-app messages
- Journeys (workflows)
- Lists
- Message types
- Metadata store
- Push notifications
- SMS
-
Subscriptions
- DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
- PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
- DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}
- PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}
- PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}
-
Templates
- GET /api/templates
- GET /api/templates/getByClientTemplateId
- GET /api/templates/email/get
- POST /api/templates/email/upsert
- POST /api/templates/email/update
- GET /api/templates/push/get
- POST /api/templates/push/upsert
- POST /api/templates/push/update
- GET /api/templates/sms/get
- POST /api/templates/sms/upsert
- POST /api/templates/sms/update
- GET /api/templates/inapp/get
- POST /api/templates/inapp/upsert
- POST /api/templates/inapp/update
-
Users
- GET /api/users/forgotten
- GET /api/users/forgottenUserIds
- POST /api/users/forget
- POST /api/users/unforget
- DELETE /api/users/{email}
- GET /api/users/{email}
- GET /api/users/getByEmail
- POST /api/users/update
- POST /api/users/bulkUpdate
- DELETE /api/users/byUserId/{userId}
- GET /api/users/byUserId/{userId}
- GET /api/users/byUserId
- POST /api/users/registerBrowserToken
- POST /api/users/updateSubscriptions
- POST /api/users/bulkUpdateSubscriptions
- POST /api/users/updateEmail
- GET /api/users/getFields
- GET /api/users/getSentMessages
- POST /api/auth/jwts/invalidate
- POST /api/users/disableDevice
- POST /api/users/registerDeviceToken
- Verify
- Webhooks
- Web push notifications
- Appendix: Project types
- Further reading
Changes to fields included in API responses
Iterable may occasionally add fields to API response bodies. Make sure that any dependencies you have on Iterable's APIs do not break if and when new fields are added.
Iterable will not rename or remove existing, documented fields from an API response body without prior communication.
TLS 1.2
To call Iterable's API, you must use a client that supports TLS 1.2.
As of October 22, 2021, API calls from clients that do not support TLS 1.2 will fail. For more information, read this release note from September 22, 2021.
Authenticating with Iterable's API
To authenticate with Iterable's API, you'll need a project-specific API key. To learn more about API keys, read API Keys.
Some important things to note about Iterable API keys:
-
Each Iterable API key is associated with a specific Iterable project, which means that it's also associated with a specific data center.
API keys created in US-based Iterable projects can only be used with Iterable's US API endpoints.
API keys created in EU-based Iterable projects can only be used with EU-based endpoints.
To authenticate a request with a non JWT-enabled API key, set the API key as the value of an
Api-Key
orApi_Key
header in your request. For more information, read API keys.To learn how to authenticate a request with a JWT-enabled API key, read JWT-Enabled API Keys.
IMPORTANT
Do not use server-side API keys in client-side (web, mobile, or otherwise) code.
Base URLs
To call Iterable's API, use the base URL associated with the Iterable data center that hosts your project.
-
US-based Iterable projects
- Base URL:
https://api.iterable.com
- For example:
https://api.iterable.com/api/events/track
- Base URL:
-
EU-based Iterable projects
- Base URL:
https://api.eu.iterable.com
- For example:
https://api.eu.iterable.com/api/events/track
- Base URL:
API reference docs
For more detail about Iterable's API (including required an optional fields), and to try sending actual API calls, visit our API reference docs:
- API docs for US-based Iterable projects: https://api.iterable.com/api/docs
- API docs for EU-based Iterable projects: https://api.eu.iterable.com/api/docs
Identifying users
Many of Iterable's API endpoints require you to specify a particular user (for example, so you can modify their user profile or fetch some data about them).
To identify a user, you'll need to provide a userId
or an email
in the body
of your API request. This field goes in the top level of your request, or
sometimes in another object that the request includes.
To decide whether to include an email
or a userId
, consider the type of
your Iterable project:
Email-based projects identify users by
email
oruserId
. However, Iterable only enforcesemail
uniqueness, notuserId
.UserID-based projects identify users by
userId
, and Iterable enforces the uniqueness of this field.Hybrid projects projects identify users by
email
and/oruserId
, and Iterable enforces the uniqueness of both. However, you don't have to give both fields to every user.
TIP
For more information about project types in Iterable, read Appendix: Project types.
Sample API request that identifies a user
To identify a user in an API request:
-
At the top level of your request (outside of
dataFields
), provide auserId
or anemail
(but not both), as required by your project type. This value tells Iterable which user to update, create, or return.If you do include both
email
anduserId
at the top level of an API request, precedence rules apply.Some requests require you to place
userId
oremail
inside another object, rather than at the top level of your API request. For example, when callingPOST /api/commerce/updateCart
, you need to placeuserId
oremail
inside auser
object.Additionally, some requests use slightly different field names. For example,
POST /api/email/target
requiresrecipientEmail
andrecipientUserId
, rather thanemail
anduserId
. For endpoint-specific details, consult our API Overview. Inside the
dataFields
object in the request, place the updates you'd like to make for that user.
For example, here's a request to POST /api/users/update
.
{ "userId": "user1234567", "dataFields": { "favoriteColor": "red" } }
If this request is sent to a userID-based or hybrid project:
If your project doesn't yet have a user with a
userId
ofuser1234567
, Iterable creates one.Then, whether the user is new or already exists, Iterable sets their
favoriteColor
tored
.
If this request is sent to an email-based project:
If there's already a user identified by a
userId
ofuser1234567
, Iterable updates theirfavoriteColor
tored
.Otherwise, the request fails. (To create a new user by
userId
in an email-based project, your request must setpreferUserId
totrue
. Sinceemail
is required in email-based projects, settingpreferUserId
totrue
also causes Iterable to assign an@placeholder.email
email address to the new user. To learn more, read Handling Anonymous Users.)
Campaigns
POST /api/campaigns/abort
Abort a campaign
API reference: US-based projects,
EU-based projects
Abort a campaign, given a campaign ID.
POST /api/campaigns/cancel
Cancel a scheduled or recurring campaign
API reference: US-based projects,
EU-based projects
Cancel a campaign, given a campaign ID.
POST /api/campaigns/trigger
Trigger a campaign
API reference: US-based projects,
EU-based projects
Trigger a campaign given lists
POST /api/campaigns/create
Create a campaign
API reference: US-based projects,
EU-based projects
Creates and schedules a blast campaign up to two weeks in advance. The campaign
has a new template with a new templateId
. If the request does not include
a sendAt
value, the message is sent immediately.
Sample request body:
{ "name": "Sample API Blast Campaign", "listIds": [ 5925, 6094 ], "templateId": 28533, "suppressionListIds": [ 6095 ], "sendAt": "2015-09-15 00:00:00" }
GET /api/campaigns/recurring/{id}/childCampaigns
Get child campaigns of a recurring campaign
API reference: US-based projects,
EU-based projects
Get details for campaigns generated by a recurring campaign.
Sample:
GET https://api.iterable.com/api/campaigns/recurring/12345/childCampaigns
GET /api/campaigns/metrics
Get metrics for campaigns
API reference: US-based projects,
EU-based projects
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
GET /api/campaigns
List campaign metadata
API reference: US-based projects,
EU-based projects
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": "user@example.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": "user@example.com", "campaignState": "Finished", "listIds": [ 14007 ], "suppressionListIds": [], "sendSize": 3 } ] }
Catalogs
GET /api/catalogs
Get catalog names
API reference: US-based projects,
EU-based projects
Lists the names of all catalogs in the project associated with an API key.
Example:
GET https://api.iterable.com/api/catalogs
Paging:
-
Use
page
andpageSize
in the query string to specify a page number and page size. For example:GET https://api.iterable.com/api/catalogs?page=3&pageSize=10
When you pass these parameters, the API returns
previousPageUrl
andnextPageUrl
values (as applicable). Use these to load more data.If you specify a
page
andpageSize
combination outside the range of available data, the API returns an empty list of catalog names.
Sample JSON response body:
{ "msg": "", "code": "Success", "params": { "catalogNames": [ { "name": "Trucks" } ], "totalCatalogsCount": 1 } }
On success, this API returns HTTP status code 200.
DELETE /api/catalogs/{catalogName}
Delete a catalog
API reference: US-based projects,
EU-based projects
Deletes a catalog and all its items.
Example:
DELETE https://api.iterable.com/api/catalogs/Trucks
Sample JSON response body:
{ "msg": "Successfully deleted catalog Trucks", "code": "Success", "params": null }
On success, this API returns HTTP status code 200.
POST /api/catalogs/{catalogName}
Create a catalog
API reference: US-based projects,
EU-based projects
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
Sample JSON response body:
{ "msg": "", "code": "Success", "params": { "id": 740, "name": "Trucks", "url": "/api/catalogs/Trucks" } }
On success, this API returns HTTP status code 201.
DELETE /api/catalogs/{catalogName}/items/{itemId}
Delete a catalog item
API reference: US-based projects,
EU-based projects
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
Sample JSON response body:
{ "msg": "Received request to deleted item ID PickupTruckA from catalog Trucks", "code": "Success", "params": null }
On success, this API returns HTTP status code 202.
GET /api/catalogs/{catalogName}/items/{itemId}
Get a specific catalog item
API reference: US-based projects,
EU-based projects
Gets the details of a specific catalog item.
Example:
GET https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA
Sample JSON response body:
{ "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.
PATCH /api/catalogs/{catalogName}/items/{itemId}
Create or update a catalog item
API reference: US-based projects,
EU-based projects
Updates (or creates) a catalog item with the values found in the request body. Any already-existing fields not included in the request body 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
Request headers:
Content-Type: application/json
Sample request body:
{ "update": { "price": 45000 } }
This request updates the `price field on the catalog item in question, but it leaves all other fields on that catalog item as is.
Do not use the period character in catalog item field names.
This request overwrites every one of the fields on
PickupTruckA
, leaving nothing except theprice
field (set to45000
).
Sample JSON response body:
{ "msg": "", "code": "Success", "params": { "catalogName": "Trucks", "itemId": "PickupTruckB", "url": "/api/catalogs/Trucks/items/PickupTruckB" } }
On success, this API returns HTTP status code 202.
PUT /api/catalogs/{catalogName}/items/{itemId}
Create or replace a catalog item
API reference: US-based projects,
EU-based projects
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 are 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 is 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
Request headers:
Content-Type: application/json
Sample request body:
{ "value": { "used": false } }
Sample JSON response body:
{ "msg": "", "code": "Success", "params": { "catalogName": "Trucks", "itemId": "PickupTruckA", "url": "/api/catalogs/Trucks/items/PickupTruckA" } }
On success, this API returns HTTP status code 202.
DELETE /api/catalogs/{catalogName}/items
Bulk delete catalog items
API reference: US-based projects,
EU-based projects
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
Request headers:
Content-Type: application/json
Sample request body:
{ "itemIds": [ "PickupTruckA", "PickupTruckB" ] }
Sample JSON response body:
{ "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 /api/catalogs/{catalogName}/items
Get the catalog items for a catalog
API reference: US-based projects,
EU-based projects
Lists all catalog items in a catalog.
Example:
GET https://api.iterable.com/api/catalogs/Trucks/items
Paging:
-
Use
page
andpageSize
in the query string to specify a page number and page size. For example:GET https://api.iterable.com/api/catalogs/Trucks/items?page=3&pageSize=10
When passing these parameters, the API returns
previousPageUrl
andnextPageUrl
values (as applicable). Use these to load more data.If you specify a
page
andpageSize
combination outside the range of available data, the API returns an empty list of catalog names.
Sample JSON response body:
{ "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.
POST /api/catalogs/{catalogName}/items
Bulk create catalog items
API reference: US-based projects,
EU-based projects
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 is 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
Request headers:
Content-Type: application/json
Sample request body:
{ "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" } } } }
Sample JSON response body:
{ "msg": "Request to bulk-upload documents into Trucks processed successfully", "code": "Success", "params": null }
On success, this API returns HTTP status code 202.
GET /api/catalogs/{catalogName}/fieldMappings
Get field mappings for a catalog
API reference: US-based projects,
EU-based projects
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
Sample JSON response body (no field types defined):
{ "msg": "", "code": "Success", "params": { "definedMappings": {}, "undefinedFields": [ "used", "current_location", "price", "manufactureDate", "options", "fullLength", "previousOwner" ] } }
Sample JSON response body (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
andstring
previousOwner
is an object containing afirstName
field and alastName
field. All three fields come back in thedefinedMappings
field if their data types have been assigned.
On success, this API returns HTTP status code 200.
PUT /api/catalogs/{catalogName}/fieldMappings
Set a catalog's field mappings (data types)
API reference: US-based projects,
EU-based projects
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
Request headers:
Content-Type: application/json
Sample request body:
{ "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 afirstName
field and alastName
field. The above request body specifies thatpreviousOwner
is an object while its children,firstName
andlastName
, are strings.It is not possible to define types for nested object fields.
Allowed types include:
boolean
,date
,geo_location
,long
,double
,object
andstring
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.
Sample JSON response body:
{ "msg": "", "code": "Success", "params": null }
On success, this API returns HTTP status code 200.
Channels
GET /api/channels
Get channels
API reference: US-based projects,
EU-based projects
Lists all of the message channels contained in the Iterable 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" } ] }
Commerce
POST /api/commerce/updateCart
Update a user's shopping cart items
API reference: US-based projects,
EU-based projects
Updates shoppingCartItems
field on the user profile.
Learn about identifying users in API requests.
NOTE
It's generally best to treat price
as a double, not a long. To do that,
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 is cast as a long.
Sample request body:
{ "user": { "email": "user@example.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.5, "quantity": 1, "imageUrl": "https://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.5, "quantity": 2, "imageUrl": "https://example.com/images/macadamianuts.jpg", "url": "iterable.com" } ] }
POST /api/commerce/trackPurchase
Track a purchase
API reference: US-based projects,
EU-based projects
Tracks when a user makes a purchase and clears shoppingCartItems
on their
profile. Including a campaignId
attributes the purchase to a specific Iterable
campaign.
Learn about identifying users in API requests.
NOTE
We recommend casting the required price
and total
fields as doubles instead
of longs. To do that, 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 is be cast as a long.
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 is updated. If
no id
is specified, a new id
is automatically generated and returned.
An id
value:
- Must contain only alphanumeric characters and hyphens.
- Must be no longer than 512 bytes in length.
- Must be unique across all purchase events in the project.
NOTE
The createdAt
field can be blank for new purchase events, and will be set to
the time the event is received. Set this value (as a Unix formatted timestamp)
only if you're sending historic events.
Sample request body:
{ "user": { "email": "user@example.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.5, "quantity": 2, "imageUrl": "https://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 } }
NOTE
The POST /api/commerce/trackPurchase
endpoint requires an array of items
, but any events that are created by
invoking this endpoint contain an array named shoppingCartItems
(not
items
).
When segmenting your users into lists, you can access data in this array by
referencing the shoppingCartItems
field (not items
).
Similarly, journeys that are triggered by trackPurchase
can access data in
this array by referencing shoppingCartItems
(not items
).
POST /api/email/cancel
Cancel an email to a user
API reference: US-based projects,
EU-based projects
Cancels an email to a specific user. Request must include a campaignId
and an
email
or userId
, or just a scheduledMessageId
.
Learn about identifying users in API requests.
POST /api/email/target
Send an email to an email address
API reference: US-based projects,
EU-based projects
Sends a triggered email campaign to specified email address. If sendAt
field
is not included, the message is sent immediately. The JSON passed in the
dataFields
section is indexed on the emailSend
event as transactionalData
.
Learn about identifying users in API requests.
NOTE
This is an asynchronous call; a 200 response means that the request has been received, not that the email has been sent.
Sample request body:
{ "campaignId": 13594, "recipientEmail": "user@example.com", "dataFields": { "customParam": "paramValue" }, "sendAt": "2015-08-31 22:00:00 +00:00" }
GET /api/email/viewInBrowser
View a previously sent email
API reference: US-based projects,
EU-based projects
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:
GET https://api.iterable.com/api/email/viewInBrowser?email=user%40example.com&messageId=340c333dea5e43cea6de24170d8a81c8
Events
POST /api/events/inAppConsume
Consume or delete an in-app message
API reference: US-based projects,
EU-based projects
Consumes or deletes an in-app message from the server.
Use this API if your app does not use one of Iterable's mobile SDKs, since they call it automatically.
Learn about identifying users in API requests.
If an incoming in-app message is not configured to use the mobile inbox, use this API to "consume" it from the server queue after the user sees it. Otherwise, call this API when the user explicitly deletes an inbox-enabled message (by clicking a delete button in its content, swiping it in the inbox, etc.).
If you pass a deleteAction
value to this endpoint, Iterable generates an
inAppDelete
event (otherwise, it does not).
Sample request body:
{ "email": "user@example.com", "userId": "user123", "messageId": "9c438a20d26e4e9f8ad4edea23f811cd", "deleteAction": "inbox-swipe", "messageContext": { "location": "inbox", "saveToInbox": true, "silentInbox": false }, "deviceInfo": { "deviceId": "A40EB980-A3F6-ACE6-4B3C-B6CFFF641F74", "platform": "iOS", "appPackageName": "com.example.testapp" } }
POST /api/events/trackInAppClick
Track an in-app message click
API reference: US-based projects,
EU-based projects
Creates an inAppClick
event for the specified user, message and URL. When not
using one of Iterable's mobile SDKs, call this endpoint when a user taps on a
button or link in an in-app message.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "user123", "messageId": "9c438a20d26e4e9f8ad4edea23f811cd", "clickedUrl": "https://www.iterable.com" }
POST /api/events/trackInAppClose
Track the closing of an in-app message
API reference: US-based projects,
EU-based projects
Creates an inAppClose
event for a specific user and in-app message. When not
using Iterable's mobile SDKs, call this endpoint to indicate that the user
tapped a close button or link to close a particular in-app message.
- Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "user123", "messageId": "9c438a20d26e4e9f8ad4edea23f811cd", "clickedUrl": "https://www.iterable.com", "messageContext": { "saveToInbox": true, "silentInbox": true, "location": "in-app" }, "closeAction": "link", "deviceInfo": { "deviceId": "", "platform": "iOS", "appPackageName": "com.example.testapp" } }
POST /api/events/trackInAppDelivery
Track the delivery of an in-app message
API reference: US-based projects,
EU-based projects
Creates an inAppDelivery
event for a specific user, device and message. When
not using Iterable's mobile SDKs, call this endpoint to indicate that a
particular message has been delivered to a particular device for a particular
user. Take care not to call this endpoint multiple times for the same
message/device/user combination.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "user123", "messageId": "9c438a20d26e4e9f8ad4edea23f811cd", "messageContext": { "saveToInbox": true, "silentInbox": true }, "deviceInfo": { "deviceId": "A40EB980-A3F6-ACE6-4B3C-B6CFFF641F74", "platform": "iOS", "appPackageName": "com.example.testapp" } }
POST /api/events/trackInAppOpen
Track an in-app message open
API reference: US-based projects,
EU-based projects
Creates an inAppOpen
event for the specified user and message. When not using
one of Iterable's mobile SDKs, call this endpoint when a mobile app displays an
in-app message to a user.
This endpoint also marks the specified in-app message as having been read.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "user123", "messageId": "9c438a20d26e4e9f8ad4edea23f811cd" }
POST /api/events/track
Track an event
API reference: US-based projects,
EU-based projects
Saves custom events in Iterable (user logins, signups, app opens, etc.).
You can use these events in segmentation, to trigger journeys, and to track custom conversions. Additionally, in a template, you can use the the fields of a campaign-triggering event as a source of dynamic data.
Learn about identifying users in API requests.
An optional string id
parameter may be passed as one of the top-level
parameters. If an event exists with that id
, the event is updated. If no id
is specified, a new id
is automatically generated and returned.
An id
value must:
- Contain only alphanumeric characters and hyphens.
- Be no longer than 512 bytes in length.
- Be unique across all custom events in the project.
Sample request body:
{ "email": "user@example.com", "eventName": "startedMembership", "id": "12345", "dataFields": { "source": "facebook", "membershipType": "monthly" }, "userId": "1", "campaignId": 123, "templateId": 123 }
POST /api/events/trackWebPushClick
Track a web push click
API reference: US-based projects,
EU-based projects
Learn about identifying users in API requests.
POST /api/events/trackPushOpen
Track a mobile push open
API reference: US-based projects,
EU-based projects
Tracks a mobile push notification open.
Include a campaignId
to attribute the open to the Iterable campaign that
sent the push notification.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "2", "campaignId": 12345, "templateId": 67890, "messageId": "9c438a20d26e4e9f8ad4edea23f811cd", "dataFields": { "openedMostRecentPush": true } }
GET /api/events/{email}
Get user events
API reference: US-based projects,
EU-based projects
Returns a user's events, including system events and custom events. The default
value for limit
is 30.
Learn about identifying users in API requests.
Sample:
GET https://api.iterable.com/api/events/user%40example.com
Sample JSON response:
{ "events": [ { "contentId": 330397, "recurringCampaignId": 12345, "email": "user@example.com", "createdAt": "2016-10-04 00:54:00 +00:00", "campaignId": 67890, "templateId": 11111, "messageId": "6b92db5f79874561bc5b1dd1337f7a35", "eventType": "emailSend" }, { "contentId": 329261, "recurringCampaignId": 12345, "email": "user@example.com", "createdAt": "2016-09-30 19:50:00 +00:00", "campaignId": 67890, "templateId": 22222, "messageId": "9c438a20d26e4e9f8ad4edea23f811cd", "eventType": "emailSend" } ] }
GET /api/events/byUserId/{userId}
Get user events by userId
API reference: US-based projects,
EU-based projects
Get events for a specific user, by userId
.
Learn about identifying users in API requests.
POST /api/events/trackBulk
Bulk track events
API reference: US-based projects,
EU-based projects
Tracks multiple custom events.
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).
Learn about identifying users in API requests.
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 request body:
{ "events": [ { "email": "user@example.com", "eventName": "startedMembership", "id": "12345", "dataFields": { "source": "facebook", "membershipType": "monthly" }, "userId": "1", "campaignId": 123, "templateId": 123 }, { "email": "user@example.com", "eventName": "quizCompleted", "id": "45678", "dataFields": { "score": 9 } } ] }
Experiments
GET /api/experiments/metrics
Get metrics for experiments
API reference: US-based projects,
EU-based projects
Get metrics for experiments(s). Note that we currently only export email experiment metrics.
Sample:
GET https://api.iterable.com/api/experiments/metrics?experimentId=12345&campaignId=23456&startDateTime=2017-06-01&endDateTime=2017-07-01
Export
CSV, JSON, and user event export APIs are synchronous, and respond with requested data:
For higher-volume requests (up to 100GB), use Iterable's async export APIs:
GET /api/export/data.csv
Export data to CSV
API reference: [US-based projects](https://api.iterable.com/api/docs#export_exportDataCsv,
EU-based projects
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.
GET /api/export/data.json
Export data to JSON
API reference: US-based projects,
EU-based projects
Exports different types of data (purchases, user created, email sends, email opens, etc) in JSON format.
Sample response:
{ "contentId": 243307, "recurringCampaignId": 41777, "email": "user@example.com", "createdAt": "2016-07-08 19:50:00 +00:00", "campaignId": 43521, "templateId": 71213 } { "contentId": 242909, "email": "user@example.com", "createdAt": "2016-07-08 16:58:19 +00:00", "campaignId": 43444, "templateId": 71115 } { "contentId": 243307, "recurringCampaignId": 41777, "email": "user2@example.com", "createdAt": "2016-07-08 19:50:00 +00:00", "campaignId": 43521, "templateId": 71213 } { "contentId": 243307, "recurringCampaignId": 41777, "email": "user3@example.com", "createdAt": "2016-07-08 19:50:00 +00:00", "campaignId": 43521, "templateId": 71213 }
NOTE
The range field pulls information based off of the profile update field.
GET /api/export/userEvents
Export user events
API reference: US-based projects,
EU-based projects
{ "name": "Jane Docs", "email": "user@example.com", "lastName": "Docs", "firstName": "Jane", "profileUpdatedAt": "2025-06-22 00:58:55 +00:00", "itblInternal": { "documentCreatedAt": "2025-06-22 00:58:55 +00:00", "documentUpdatedAt": "2025-06-22 00:58:55 +00:00" }, "createdAt": "2020-06-22 00:58:55 +00:00", "signupSource": "Import", "messageTypeIds": [], "emailListIds": [ 1111111 ], "channelIds": [], "_type": "emailSubscribe" } { "_id": "50bc32394fa14ef8dh24a17b5b6da768", "eventName": "viewedItem", "email": "user@example.com", "viewedItem": { "email": "user@example.com" }, "createdAt": "2025-06-28 02:12:02 +00:00", "eventUpdatedAt": "2025-06-28 02:12:02 +00:00", "itblInternal": { "documentCreatedAt": "2025-06-28 02:12:02 +00:00", "documentUpdatedAt": "2025-06-28 02:12:02 +00:00" }, "_type": "customEvent" }
POST /api/export/start
Start export
API reference: US-based projects,
EU-based projects
Starts a data export. The export processes as a background job.
Request either CSV or JSON files. For
outputFormat
, providetext/csv
orapplication/x-json-stream
.-
Specify the type of data you're requesting. For
dataTypeName
, provide one of the following values:customEvent
,emailBounce
,emailClick
,emailComplaint
,emailOpen
,emailSend
,emailSendSkip
,emailSubscribe
,emailUnSubscribe
,embeddedClick
,embeddedDismiss
,embeddedImpression
,embeddedReceived
,embeddedSend
,embeddedSendSkip
,hostedUnsubscribeClick
,inAppClick
,inAppClose
,inAppDelete
,inAppDelivery
,inAppOpen
,inAppRecall
,inAppSend
,inAppSendSkip
,inboxMessageImpression
,inboxSession
,purchase
,pushBounce
,pushOpen
,pushSend
,pushSendSkip
,pushUninstall
,smsBounce
,smsClick
,smsReceived
,smsSend
,smsSendSkip
,smsUsageInfo
,user
,webPushClick
,webPushSend
,webPushSendSkip
-
To refine your request, use any of the following optional filters:
-
startDateTime
- Export events occurring or users updated after date and time inclusive (yyyy-MM-dd HH:mm:ss [ZZ]
) -
endDateTime
- Export events occurring or users updated before date and time exclusive (yyyy-MM-dd HH:mm:ss [ZZ]
) -
omitFields
- Fields to omit from the export (comma-separated) -
onlyFields
- If non-empty, only include these fields in the export (comma-separated) -
campaignId
- Only export data from this campaign -
delimiter
- CSV file delimiter
-
Save the returned
jobId
to check job status and retrieve export files usingGET /api/export/{jobId}/files
.
Sample request body:
{ "outputFormat": "text/csv", "dataTypeName": "user", "startDateTime": "2025-01-01", "endDateTime": "2025-03-01", "onlyFields": "email,locale,firstName,lastName" }
Sample response body:
{ "jobId": 99999 }
GET /api/export/{jobId}/files
Get export files
API reference: US-based projects,
EU-based projects
Gets the job status and links for exported files with the
POST /api/export/start
endpoint.
Paginate through the files by using the last file name in the response as the
startAfter
value for the next request. Iterable returns up to 10 files per
request.
Export files have secured links to a private Iterable repository. The links are valid for 1 hour, and after that time you must request new links. After 7 days, the files are deleted. After 30 days, all information about the job is deleted.
Example: GET /api/export/{jobId}/files?startAfter=file-name.csv
Files are added to the list as the job is running.
Exports are limited to 100 GB in total size, with files up to 10MB each.
Sample response body:
{ "jobId": 99999, "jobState": "completed", "exportTruncated": false, "files": [ { "file": "file-name.csv", "url": "<some-URL>" } ] }
DELETE /api/export/{jobId}
Cancel export
API reference: US-based projects,
EU-based projects
Cancels a queued or running export created with the
POST /api/export/start
endpoint.
In-app messages
GET /api/inApp/getPriorityMessage
Get a user's most relevant in-app message
API reference: US-based projects,
EU-based projects
Get a user's most relevant in-app message.
Learn about identifying users in API requests.
GET /api/inApp/getMessages
Get a user's in-app messages
API reference: US-based projects,
EU-based projects
Gets the in-app messages available for a specific user. This endpoint returns
new messages and messages that have already been saved to a user's mobile inbox.
Each message has a read
field that indicates whether or not it has already
been seen.
If you'd like this API to return selective in-app messages for a specific
app/platform combination (as well as non-selective in-app messages), include
packageName
and platform
as query parameters in your request.
If you don't include both of these parameters, the API returns only non-selective in-app messages (i.e., in-app messages sent with the selective in-app messaging feature disabled).
Sample request:
GET https://api.iterable.com/api/inApp/getMessages?email=user%40example.com&userId=1234&count=123
Sample JSON response:
{ "inAppMessages": [ { "messageId": "9c438a20d26e4e9f8ad4edea23f811cd", "campaignId": 0, "createdAt": "2022-11-10T16:58:14.933Z", "expiresAt": "2022-11-10T16:58:14.933Z", "content": { "html": "string", "inAppDisplaySettings": { "top": {}, "right": {}, "bottom": {}, "left": {}, "bgColor": { "alpha": 0, "hex": "string" }, "shouldAnimate": true }, "webInAppDisplaySettings": { "position": {} } }, "customPayload": {}, "trigger": { "type": {} }, "saveToInbox": true, "inboxMetadata": { "title": "string", "subtitle": "string", "icon": "string" }, "priorityLevel": 0, "read": true, "jsonOnly": true, "typeOfContent": {}, "messageType": {} } ] }
priorityLevel
indicates an in-app messages's display priority:
- Proof: 100.0
- Critical: 100.5
- High: 200.5
- Medium: 300.5
- Low: 400.5
By default, Iterable's mobile SDKs display greater priority messages first (proof, then critical, then high, then medium, then low), sorting the messages in each individual priority level by send time (first sent, first displayed).
POST /api/inApp/cancel
Cancel a scheduled in-app message
API reference: US-based projects,
EU-based projects
Cancels the sending of a scheduled in-app message to a specific user.
Sample JSON body:
{ "email": "user@example.com", "campaignId": 13770 }
Learn about identifying users in API requests.
POST /api/inApp/target
Send an in-app notification to a user
API reference: US-based projects,
EU-based projects
Sends an existing in-app message campaign to a specific user. Use sendAt
to
schedule a future send and dataFields
to override user profile fields.
Sample JSON body:
{ "campaignId": 13770, "recipientEmail": "user@example.com", "dataFields": { "newUser": "FALSE" }, "sendAt": "2016-08-25 23:25:00 +00:00" }
Learn about identifying users in API requests.
Web in-app messages
GET /api/inApp/web/getMessages
Get a user's web in-app messages
API reference: US-based projects,
EU-based projects
This endpoint is functionally the same as GET /api/inApp/getMessages
,
but with platform
always set to Web
(cannot be changed).
This endpoint is used by Iterable's web SDK to fetch in-browser messages (in-app messages that target a website).
Journeys (workflows)
POST /api/workflows/triggerWorkflow
Trigger a workflow
API reference: US-based projects,
EU-based projects
Triggers a journey for a single user and/or all users on a list. Works for both standard and dynamic lists.
Learn about identifying users in API requests.
Sample request body (JSON):
{ "email": "user@example.com", "workflowId": 2765, "listId": 6094, "dataFields": { "signupSource": "google", "optIn": true } }
Lists
DELETE /api/lists/{listId}
Delete a list
API reference: US-based projects,
EU-based projects
Deletes a list. All users who are part of the deleted list have the list removed from their profile.
Sample request:
https://api.iterable.com/api/lists/21398
GET /api/lists
Get lists
API reference: US-based projects,
EU-based projects
Returns the project's static lists and their descriptions (if set).
Sample:
GET https://api.iterable.com/api/lists
Sample response body:
{ "lists": [ { "id": 12345, "name": "September subscribers", "description": "Users who subscribed in September 2022.", "createdAt": 1234567891011, "listType": "Standard" } ] }
POST /api/lists
Create a static list
API reference: US-based projects,
EU-based projects
Creates a new, empty, standard list, with the specified name. Returns the list ID.
Sample request body:
{ "name": "September subscribers", "description": "Users who subscribed in September 2022." }
POST /api/lists/subscribe
Add subscribers to list
API reference: US-based projects,
EU-based projects
Adds a subscriber to an existing static list.
Learn about identifying users in API requests.
Sample request body:
{ "listId": 123, "subscribers": [ { "email": "user@example.com", "dataFields": { "firstName": "Sherry", "hasCat": true }, "userId": "1" } ] }
POST /api/lists/unsubscribe
Remove users from a list
API reference: US-based projects,
EU-based projects
Removes one or more subscribers from an existing static list.
Learn about identifying users in API requests.
Sample request body:
{ "listId": 1, "subscribers": [ { "email": "user@example.com" }, { "email": "user2@example.com" } ], "campaignId": 123, "channelUnsubscribe": false }
GET /api/lists/getUsers
Get users in a list
API reference: US-based projects,
EU-based projects
Returns a string of all the users who are on a list. Works for both static and dynamic lists
Sample:
GET https://api.iterable.com/api/lists/getUsers?listId=21401
GET /api/lists/{listId}/size
Get count of users in list
API reference: US-based projects,
EU-based projects
Get the number of users within a list.
Message types
GET /api/messageTypes
List message types
API reference: US-based projects,
EU-based projects
Lists all message types in the 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 } ] }
Metadata store
DELETE /api/metadata/{table}/{key}
Delete a single metadata key/value
API reference: US-based projects,
EU-based projects
Deletes the specified item from the table.
Asynchronous. 200
response indicates a valid request that will be processed.
Data may not be deleted immediately. To verify completion, call
GET /api/metadata/{table}/{key}
.
GET /api/metadata/{table}/{key}
Get the metadata value of a single key
API reference: US-based projects,
EU-based projects
Get the metadata value of a single key.
PUT /api/metadata/{table}/{key}
Create or replace metadata
API reference: US-based projects,
EU-based projects
Creates or replaces the item associated with the specified key.
Asynchronous. 200
response indicates a valid request that will be processed.
Updates may not be made immediately. To verify completion, call
GET /api/metadata/{table}/{key}
.
DELETE /api/metadata/{table}
Delete a table
API reference: US-based projects,
EU-based projects
Deletes a specified table.
Asynchronous. 200 response indicates a valid request that will be processed.
Table may not be deleted immediately. To verify completion, call
GET /api/metadata/{table}
.
GET /api/metadata/{table}
List keys in a table
API reference: US-based projects,
EU-based projects
List keys in a given table.
GET /api/metadata
List available tables
API reference: US-based projects,
EU-based projects
List available tables.
Push notifications
POST /api/push/cancel
Cancel a push notification to a user
API reference: US-based projects,
EU-based projects
Cancels a push notification to a specific user. Request must include a
campaignId
and an email
or userId
, or just a scheduledMessageId
.
Learn about identifying users in API requests.
POST /api/push/target
Send push notification to user
API reference: US-based projects,
EU-based projects
Sends a triggered push notification to a specific user.
Request data fields override existing user profile data fields. Campaign must be
set up in Iterable beforehand. If sendAt
field is not included, the message is
sent immediately.
Learn about identifying users in API requests.
Sample request body:
{ "campaignId": 13770, "recipientEmail": "user@example.com", "dataFields": { "newUser": "FALSE" }, "sendAt": "2016-08-25 23:25:00 +00:00" }
SMS
POST /api/sms/cancel
Cancel an SMS to a user
API reference: US-based projects,
EU-based projects
Cancels an SMS to a specific user. Must include either an email
address AND
campaignId
, or just a scheduledMessageId
.
Sample request body:
{ "email": "user@example.com", "campaignId": 15354, "scheduledMessageId": "210badf49fe54f2591d64ad0d055f4fb", "userId": "1" }
Learn about identifying users in API requests.
POST /api/sms/target
Send SMS notification to user
API reference: US-based projects,
EU-based projects
Sends an SMS to a specific user. Request data fields override existing user
profile data fields. Campaign must be set up in Iterable beforehand. If sendAt
field is not included, the message is sent immediately.
Learn about identifying users in API requests.
Sample request body:
{ "campaignId": 13770, "recipientEmail": "user@example.com", "dataFields": { "newUser": "FALSE" }, "sendAt": "2016-08-25 23:25:00 +00:00" }
Subscriptions
DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
Unsubscribe a single user
API reference: US-based projects,
EU-based projects
-
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
user@example.com
from message type12345
:DELETE https://api.iterable.com/api/subscriptions/messageType/12345/user/user%40example.com
Learn about identifying users in API requests.
PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
Subscribe a single user
API reference: US-based projects,
EU-based projects
-
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
user@example.com
to message type12345:
PATCH https://api.iterable.com/api/subscriptions/messageType/12345/user/user%40example.com
Learn about identifying users in API requests.
DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}
Unsubscribe a single user by userId
API reference: US-based projects,
EU-based projects
Learn about identifying users in API requests.
-
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
userId
, provide the user ID 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
101abc123
to message type12345
:DELETE https://api.iterable.com/api/subscriptions/messageType/12345/user/101abc123
PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}
Subscribe a single user by their userId
API reference: US-based projects,
EU-based projects
-
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
userId
, provide the user ID 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
101abc123
to message type12345:
PATCH https://api.iterable.com/api/subscriptions/messageType/12345/user/101abc123
Learn about identifying users in API requests.
PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}
Bulk subscription action on a list of users
API reference: US-based projects,
EU-based projects
To subscribe multiple users to the same channel, message type or list, use
action=subscribe
(as shown in the above URL). To unsubscribe, useaction=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 request body, provide a
users
array containing the email addresses of the users to subscribe or unsubscribe, and/or ausersByUserId
array containing theuserId
values to subscribe. Learn about identifying users in API requests.This is an asynchronous API. It returns 202 on success.
-
For example, the following request subscribes
user@example.com
,user2@example.com
, anduser1234567
to message type12345
:PUT https://api.iterable.com/api/subscriptions/messageType/12345
Request body:
{ "users": [ "user@example.com", "user2@example.com" ], "usersByUserId": [ "user1234567" ] }
Templates
IMPORTANT
Iterable's template APIs allow you to read and update all templates. They are not restricted to base templates — you can use them to read and update templates associated with blast campaigns, triggered campaigns, and journey campaigns, changing their content for future sends.
GET /api/templates
Get project templates
API reference: US-based projects,
EU-based projects
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
If you leave templateType
blank, the endpoint returns base templates only.
Sample:
GET https://api.iterable.com/api/templates?templateType=Base&messageMedium=Email
Sample JSON response:
{ "templates": [ { "templateId": 86596, "createdAt": 1473368899828, "updatedAt": 1473370111852, "name": "Regular editor", "creatorUserId": "user@example.com", "messageTypeId": 3867 }, { "templateId": 68178, "createdAt": 1466810056349, "updatedAt": 1470431713441, "name": "Photography Welcome Message", "creatorUserId": "user@example.com", "messageTypeId": 3866 } ] }
GET /api/templates/getByClientTemplateId
Get an email template by clientTemplateId
API reference: US-based projects,
EU-based projects
Gets 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 return those
templates.
GET /api/templates/email/get
Get an email template by templateId
API reference: US-based projects,
EU-based projects
Returns HTML and metadata for a specific email template.
Sample JSON response:
{ "templateId": 86596, "name": "My name of template", "fromName": "Customer Success", "fromEmail": "user@example.com", "replyToEmail": "replyTo@example.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": "user@example.com" }
POST /api/templates/email/upsert
Create email template
API reference: US-based projects,
EU-based projects
Creates a new email template if one does not exist, or updates all templates with the specified client template id.
Sample request body:
{ "clientTemplateId": 112233, "name": "Lots of Cats", "fromName": "Felicia the Cat", "fromEmail": "user@example.com", "replyToEmail": "replyTo@example.com", "subject": "Rank These Cats", "preheaderText": "10 out of 10!", "html": "<html><body><p>So many cats!</p></body></html>" }
POST /api/templates/email/update
Update email template
API reference: US-based projects,
EU-based projects
Updates a specific email template. Only fields specified are updated.
Sample request body:
{ "templateId": 53081, "name": "Lots of Cats", "fromName": "Felicia the Cat", "fromEmail": "replyto@example.com", "replyToEmail": "replyto@example.com", "subject": "Rank These Cats", "preheaderText": "10 out of 10!", "html": "<html><body><p>So many cats!</p></body></html>" }
NOTE
This call does not work on templates made with the Drag and Drop Editor.
GET /api/templates/push/get
Get a push template
API reference: US-based projects,
EU-based projects
Returns content and metadata for a specific push notification template.
Sample JSON response:
{ "templateId": 0, "createdAt": "2022-09-29T17:23:42.748Z", "updatedAt": "2022-09-29T17:23:42.748Z", "name": "string", "title": "string", "message": "string", "payload": {}, "badge": "string", "wake": true, "relevanceScore": 0, "interruptionLevel": "passive", "locale": "string", "messageTypeId": 0, "sound": "string", "buttons": [ { "identifier": "string", "title": "string", "buttonType": "default", "action": { "type": "string", "data": "string" }, "openApp": true, "requiresUnlock": true, "inputPlaceholder": "string", "inputTitle": "string", "actionIcon": { "iconType": {}, "imageName": "string" } } ], "deeplink": { "ios": "string", "android": "string" }, "richMedia": { "ios": "string", "android": "string" }, "dataFeedIds": [ 0 ], "cacheDataFeed": true, "mergeDataFeedContext": true, "clientTemplateId": "string", "campaignId": {}, "isSilentPush": true }
POST /api/templates/push/upsert
Create a push template
API reference: US-based projects,
EU-based projects
Creates a new template if one does not exist, or updates all templates with the specified name.
Sample request body:
{ "clientTemplateId": "string", "name": "string", "title": "string", "message": "string", "payload": { "underlying": {}, "fields": [ { "_1": "string", "_2": {} } ], "value": {} }, "badge": "string", "wake": true, "relevanceScore": 0, "interruptionLevel": "passive", "locale": "string", "messageTypeId": 0, "sound": "string", "buttons": [ { "identifier": "string", "title": "string", "buttonType": "default", "action": { "type": "string", "data": "string" }, "openApp": true, "requiresUnlock": true, "inputPlaceholder": "string", "inputTitle": "string", "actionIcon": { "iconType": {}, "imageName": "string" } } ], "deeplink": { "ios": "string", "android": "string" }, "richMedia": { "ios": "string", "android": "string" }, "dataFeedIds": [ 0 ], "cacheDataFeed": true, "mergeDataFeedContext": true, "creatorUserId": "string", "isSilentPush": true, "messageMedium": {} }
POST /api/templates/push/update
Update push template
API reference: US-based projects,
EU-based projects
Updates a specific push template. Most fields are optional. Include the fields you wish to update.
Sample request body:
{ "templateId": 0, "createdAt": "2022-09-29T17:23:42.683Z", "updatedAt": "2022-09-29T17:23:42.683Z", "name": "string", "title": "string", "message": "string", "payload": {}, "badge": "string", "wake": true, "relevanceScore": 0, "interruptionLevel": "passive", "locale": "string", "messageTypeId": 0, "sound": "string", "buttons": [ { "identifier": "string", "title": "string", "buttonType": "default", "action": { "type": "string", "data": "string" }, "openApp": true, "requiresUnlock": true, "inputPlaceholder": "string", "inputTitle": "string", "actionIcon": { "iconType": {}, "imageName": "string" } } ], "deeplink": { "ios": "string", "android": "string" }, "richMedia": { "ios": "string", "android": "string" }, "dataFeedIds": [ 0 ], "cacheDataFeed": true, "mergeDataFeedContext": true, "clientTemplateId": "string", "campaignId": {}, "isSilentPush": true }
To indicate that a template should send as a silent push notification, rather
than a standard push notification, set isSilentPush
to true
.
Silent push notifications don't visibly appear to your user. Instead, they pass
JSON data to your app (the payload
), which can use this data as needed — to
kick off a download, to tell the app to display an app store review prompt, etc.
On iOS, you can also use a silent push to set the badge
field, which updates
the badge on your app's icon.
GET /api/templates/sms/get
Get an SMS template
API reference: US-based projects,
EU-based projects
Returns content and metadata for a specific SMS template.
Sample JSON response:
{ "templateId": 100692, "name": "SMS testing", "message": "Here is example message", "messageTypeId": 4769 }
POST /api/templates/sms/upsert
Create an SMS template
API reference: US-based projects,
EU-based projects
Creates a new template if one does not exist or updates all templates with the specified client template id.
Sample request body:
{ "clientTemplateId": 112233, "name": "SMS Test", "message": "Hello There!", "locale": "en", "messageTypeId": "1234" }
POST /api/templates/sms/update
Update SMS template
API reference: US-based projects,
EU-based projects
Updates a specific SMS template. Most fields are optional. Include the fields you wish to update.
Sample request body:
{ "templateId": 123, "name": "My SMS Title", "message": "I like animals.", "locale": "fr", "messageTypeId": 531 }
GET /api/templates/inapp/get
Get an in-app template
API reference: US-based projects,
EU-based projects
Gets an in-app template, by templateId
and locale
.
POST /api/templates/inapp/upsert
Create an in-app template
API reference: US-based projects,
EU-based projects
Create an in-app template if it doesn't exist yet, otherwise update all in-app templates which match the name provided.
POST /api/templates/inapp/update
Update in-app template
API reference: US-based projects,
EU-based projects
Updates an in-app template.
Users
GET /api/users/forgotten
Get hashed forgotten users in compliance with GDPR
API reference: US-based projects,
EU-based projects
Returns a hash for each email address currently forgotten by your project. Each forgotten email is lowercased, trimmed, and hashed using SHA-256. This endpoint only works for email-based and hybrid projects. For userID-based projects, it returns an error.
Learn about identifying users in API requests.
GET /api/users/forgottenUserIds
Get hashed forgotten userIds in compliance with GDPR
API reference: US-based projects,
EU-based projects
Returns a hash for each userId
currently forgotten by your project. Each
forgotten userId is lowercased, trimmed, and hashed using SHA-256. This endpoint
only works for userID-based and hybrid projects. For email-based projects, it
returns an error.
POST /api/users/forget
Forget a user in compliance with GDPR
API reference: US-based projects,
EU-based projects
IMPORTANT
- It can take up to ten minutes for Iterable to forget a user.
- Use this endpoint only for handling right to be forgotten requests.
This endpoint:
- Deletes the user's data from the Iterable project.
- Prevents Iterable from collecting more information about or sending messages to that user.
For a given user, call this endpoint for each project necessary.
Before forgetting or unforgetting a user, consider your project type:
- In email-based projects, you must forget and unforget users by
email
, notuserId
. - In userID-based projects, you must forget and unforget users by
userId
, notemail
. - In hybrid projects, you can forget and unforget users by
email
oruserId
(and you can use one identifier to forget, and the other to unforget).
TIP
For more information, read Responding to GDPR Requests.
POST /api/users/unforget
Unforget a user in compliance with GDPR
API reference: US-based projects,
EU-based projects
Restores a given Iterable project's ability to store information about and send messages to a user who had previously been forgotten. However, it does not recover any data stored about the user before they were forgotten.
For a given user, call this endpoint for each project necessary.
Before forgetting or unforgetting a user, consider your project type:
- In email-based projects, you must forget and unforget users by
email
, notuserId
. - In userID-based projects, you must forget and unforget users by
userId
, notemail
. - In hybrid projects, you can forget and unforget users by
email
oruserId
(and you can use one identifier to forget, and the other to unforget).
TIP
For more information, read Responding to GDPR Requests.
DELETE /api/users/{email}
Delete a user by email
API reference: US-based projects,
EU-based projects
WARNING
This endpoint completely deletes the specified user profile, including subscription settings and event history. If the user is ever re-added, their profile will be empty and subscribed to everything by default. Deleting a user removes their historic campaign metrics, too.
Sample:
DELETE https://api.iterable.com/api/users/user%40example.com
Before deleting users, consider your project type.
In email-based projects and hybrid projects, you can delete users by email
or
userId
. In userID-based projects, you can delete users only by userId
.
GET /api/users/{email}
Get a user by email (path parameter)
API reference: US-based projects,
EU-based projects
Get a user by email address (passed as a path parameter).
If the email address contains non-alphanumeric characters, use
GET /api/users/getByEmail
instead.
Sample:
GET https://api.iterable.com/api/users/user%40example.com
Learn about identifying users in API requests.
GET /api/users/getByEmail
Get a user by email (query parameter)
API reference: US-based projects,
EU-based projects
Get a user by email address (passed as a query parameter).
Returns the same data as GET /api/users/{email}
, but
supports email values that contain non-alphanumeric characters, which should be
URL-encoded before being passed to this endpoint.
Learn about identifying users in API requests.
POST /api/users/update
Update user data
API reference: US-based projects,
EU-based projects
Updates a user profile with the specified data. Learn about identifying users in API requests.
If you set mergeNestedObjects
to true
(defaults to false
), the API merges
data in top-level objects rather than overwriting it with the values found
on the request.
For example, consider this user profile:
{ "email": "user@example.com", "mySettings": { "mobile": true } }
And this API request to POST /api/users/update
:
{ "email": "user@example.com", "mergeNestedObjects": true, "dataFields": { "mySettings": { "email": true } } }
Because mergeNestedObjects
was true
, the resulting user profile is:
{ "email": "user@example.com", "mySettings": { "mobile": true, "email": true } }
If mergeNestedObjects
had been false
, the resulting user profile would
instead have been:
{ "email": "user@example.com", "mySettings": { "email": true } }
POST /api/users/bulkUpdate
Bulk update user data
API reference: US-based projects,
EU-based projects
Bulk updates user data. This endpoint adds and overwrites user profile fields as needed. It does not modify top-level fields omitted from the request body.
Learn about identifying users in API requests.
If you'd like to merge (rather than overwrite) a user profile's top-level
objects with the values provided for them in the request body, set
mergeNestedObjects
to true.
When updating an existing field, you cannot change its data type (the new value must have the same data type as the old value).
When adding a new field, remember that each project has a soft limit of 1,000 unique user profile fields (across all its users, with a field's uniqueness determined by its name and position on the user profile).
Iterable handles requests to this endpoint separately from requests to
single-user endpoints (update
, updateEmail
, updateSubscriptions
, etc.). For a
given user, in a short period of time, only use single-user calls or bulk update
calls. Otherwise, results may be inconsistent.
When updating the emailListIds
field, this endpoint does not generate subscribe
or unsubscribe events. The same is true for updates to unsubscribedChannelIds
and unsubscribedMessageTypeIds
(but these can only be updated by this endpoint
in projects where the opt-in message types feature is not enabled).
To create a user profile for a user without a known email address:
- For email-based projects, specify a
userId
and setpreferUserId
totrue
. - For userID-based and hybrid projects, specify a
userId
. - To learn more, read Handling Anonymous Users.
Sample request body:
{ "users": [ { "email": "user@example.com", "userId": "0192837821", "dataFields": { "favoriteColor": "orange" } }, { "email": "user2@example.com", "userId": "9281928374", "dataFields": { "favoriteColor": "blue" } }, { "userId": "2394029394", "preferUserId": true, "dataFields": { "favoriteColor": "red" } } ] }
DELETE /api/users/byUserId/{userId}
Delete user by userId
API reference: US-based projects,
EU-based projects
Deletes a user (identified by userId
).
WARNING
This endpoint completely deletes the specified user profile, including subscription settings and event history. If the user is ever re-added, their profile will be empty and subscribed to everything by default. Deleting a user removes their historic campaign metrics, too.
Sample:
GET https://api.iterable.com/api/users/byUserId/{userId}
Before deleting users, consider your project type.
In email-based projects and hybrid projects, you can delete users by email
or
userId
. In userID-based projects, you can delete users only by userId
.
GET /api/users/byUserId/{userId}
Get a user by userId (path parameter)
API reference: US-based projects,
EU-based projects
Get a user by userId
(passed as a path parameter).
If the userId
address contains non-alphanumeric characters, use
GET /api/users/byUserId
instead.
Sample:
GET https://api.iterable.com/api/users/byUserId?userId=testUserId
Learn about identifying users in API requests.
GET /api/users/byUserId
Get a user by userId (query parameter)
API reference: US-based projects,
EU-based projects
Get a user by userId
address (passed as a query parameter).
Returns the same data as GET /api/users/byUserId/{userId}
,
but supports userId
values that contain non-alphanumeric characters, which
should be URL-encoded before being passed to this endpoint.
Learn about identifying users in API requests.
POST /api/users/registerBrowserToken
Register a browser token for web push
API reference: US-based projects,
EU-based projects
Learn about identifying users in API requests.
POST /api/users/updateSubscriptions
Update user subscriptions
API reference: US-based projects,
EU-based projects
Updates a user's subscription settings with new settings.
This endpoint overwrites existing subscription preferences if those fields are set
and not null
.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "0192837821", "emailListIds": [ 5, 6, 7 ], "unsubscribedChannelIds": [ 100 ], "unsubscribedMessageTypeIds": [ 100 ], "campaignId": 123, "templateId": 123 }
POST /api/users/bulkUpdateSubscriptions
Bulk update user subscriptions
API reference: US-based projects,
EU-based projects
Updates one or more users' subscription preferences. Include campaignId
and/or
templateId
to attribute unsubscribes to campaigns and templates.
Learn about identifying users in API requests.
NOTE
This endpoint overwrites existing subscription preferences if fields are set and not null.
Sample request body:
{ "updateSubscriptionsRequests": [ { "email": "user@example.com", "userId": "0192837821", "unsubscribedChannelIds": [ 12345, 23456 ], "unsubscribedMessageTypeIds": [ 65432 ], "campaignId": 34567, "templateId": 456789 }, { "email": "user2@example.com", "userId": "2131238573", "unsubscribedChannelIds": [ 12345 ], "campaignId": 34567, "templateId": 456789 } ] }
POST /api/users/updateEmail
Update user email
API reference: US-based projects,
EU-based projects
Updates a user's email.
IMPORTANT
Use this endpoint with email-based projects. To update
an email in a userID-based or hybrid project, use POST /api/users/update
.
In the request body, specify currentEmail
or currentUserId
, but not both. If
you provide both, currentEmail
takes precedence.
Sample request body:
{ "currentEmail": "oldEmail@example.com", "newEmail": "newEmail@example.com" }
Another sample request body:
{ "currentUserId": "user1234567", "newEmail": "newEmail@example.com" }
Returns an error if the new email already exists in Iterable, or if the new email has been forgotten via a GDPR request.
Learn more about identifying users in API requests.
GET /api/users/getFields
Get all user fields
API reference: US-based projects,
EU-based projects
Gets all user profile fields in a project.
Sample:
GET https://api.iterable.com/api/users/getFields
Sample JSON response:
{ "fields": { "phoneNumber": "string", "email": "string", "lastName": "string", "firstName": "string", "signupDate": "date", "profileUpdatedAt": "date", "signupSource": "string" } }
GET /api/users/getSentMessages
Get messages sent to a user
API reference: US-based projects,
EU-based projects
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:
GET https://api.iterable.com/api/users/getSentMessages?email=user%40example.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
Sample JSON response:
{ "messages": [ { "messageId": "9c438a20d26e4e9f8ad4edea23f811cd", "campaignId": 123, "templateId": 456, "createdAt": "2016-10-04 00:54:00 +00:00" }, { "messageId": "9c438a20d26e4e9f8ad4edea23f811cd", "campaignId": 321, "templateId": 654, "createdAt": "2016-09-30 19:50:00 +00:00" } ] }
POST /api/auth/jwts/invalidate
Invalidate all JWTs issued for a user
API reference: US-based projects,
EU-based projects
Invalidates all JWTs issued for a given user before the current time or a specified time.
POST /api/users/disableDevice
Disable pushes to a mobile device
API reference: US-based projects,
EU-based projects
Disables device. Prevents it from receiving push notifications. Must include the device token.
Learn about identifying users in API requests.
If the token exists on multiple user profiles, including email
disables
the token for that one email address only. If email
is not included, the toke
is disabled from all user profiles. The same is true for including or not
including userId
.
Sample request body:
{ "token": "sampleToken123", "email": "user@example.com", "userId": "2" }
POST /api/users/registerDeviceToken
Register a device token for push
API reference: US-based projects,
EU-based projects
Registers a mobile device token to enable push notifications.
applicationName
is usually be the package name of your mobile app, as found
in Settings > Apps and websites.
Learn about identifying users in API requests.
TIP
Learn more about sending push notifications with Iterable.
Sample request body:
{ "email": "user@example.com", "device": { "token": "sampletoken123", "platform": "APNS", "applicationName": "com.example.pizzatracker", "dataFields": { "phoneType": "iPhone 6 plus" } }, "userId": "2" }
Verify
POST /api/verify/sms/begin
Begin SMS Verification
API reference: US-based projects,
EU-based projects
Sends an SMS verification code to phoneNumber
, using the specified
verificationProfileId
.
Verification codes are sent from a pool of sender IDs reserved for this purpose, not from your sender IDs.
Sample request body:
{ "verificationProfileId": 12345, "phoneNumber": "+14155550132" }
To find a verificationProfileId
, look on the Settings > Sending Platforms
page in Iterable. Open the Twilio or Telnyx account you use to send SMS
verification messages, open the Verification Profiles menu, and grab a
verification profile ID from the right-most column.
Call this endpoint only for projects that use Iterable SMS to send SMS messages. If you use your own Twilio or Telnyx account, call their verification endpoints directly.
To use this endpoint, first ask your Iterable customer success manager to add SMS phone verification to your project. To learn more, read SMS Phone Verification
POST /api/verify/sms/check
Check SMS Verification Code
API reference: US-based projects,
EU-based projects
Checks whether the code
included in the request body matches the most recent,
non-expired, not-yet-verified SMS verification code sent to phoneNumber
by the
specified verificationProfileId
.
Sample request body:
{ "verificationProfileId": 12345, "phoneNumber": "+14155550132", "code": "13579" }
To find a verificationProfileId
, look on the Settings > Sending Platforms
page in Iterable. Open the Twilio or Telnyx account you use to send SMS
verification messages, open the Verification Profiles menu, and grab a
verification profile ID from the right-most column.
For code
, provide the code entered by your users in your mobile app or website
after you sent them a verification SMS.
If code
is correct, this endpoint returns a 200
response with a JSON body
that has a params
object with status
set to verified
. For example:
{ "msg": "", "code": "Success", "params": { "status": "verified" } }
If code
is incorrect, this endpoint returns a 200
response with a JSON body
that has a params
object with status
set to rejected
. For example:
{ "msg": "incorrect verification code", "code": "Success", "params": { "status": "rejected" } }
Call this endpoint only for projects that use Iterable SMS to send SMS messages. If you use your own Twilio or Telnyx account, call their verification endpoints directly.
To use this endpoint, first ask your Iterable customer success manager to add SMS phone verification to your project. To learn more, read SMS Phone Verification
Webhooks
GET /api/webhooks
Get webhooks
API reference: US-based projects,
EU-based projects
List the webhooks in the project.
POST /api/webhooks
Update webhook
API reference: US-based projects,
EU-based projects
Update a webhook.
Web push notifications
POST /api/webPush/cancel
Cancel a web push notification to a user
API reference: US-based projects,
EU-based projects
Cancels a web push notification to a specific user. Request must include a
campaignId
and an email
or userId
, or just a scheduledMessageId
.
Learn about identifying users in API requests.
POST /api/webPush/target
Send web push notification to user
API reference: US-based projects,
EU-based projects
Sends a web push notification to a specific user. Request data fields override
user profile data fields. A reference to the user profile is provided via the
profile
field, to help resolve field collisions.
Learn about identifying users in API requests.
Appendix: Project types
When creating a new Iterable project, you'll select a project type: email-based, userID-based, or hybrid. Each project types identifies its users in a different way, which affects how you identify users in API calls.
TIPS
- After reading the following information about Iterable's different project types, learn more by reading Project Types and Unique Identifiers.
- Iterable's European Data Center (EUDC) supports userID-based and hybrid projects, but not email-based projects.
Email-based projects
Email-based projects identify users by email
. As you create users and give
them email
addresses, Iterable enforces email
uniqueness.
In these projects, you can also identify users by userId
, but Iterable does
not enforce userId
uniqueness. Because of this, if you're not careful, you
can give the same userId
to multiple users. This can lead to unpredictable
results when making API calls.
To identify a user in an API call to an email-based project, add an email
or a
userId
(but not both) to the top level of your API request (outside of
dataFields
). If you provide both, email
takes precedence.
TIP
When calling the GDPR forget and unforget endpoints in an email-based project,
you must use email
, not userId
.
Creating new users in email-based projects
To use Iterable's API (in an email-based project) to create a new user and assign them a unique email address, make a request to one of the various endpoints that can create new users:
- Update user data (individually or in bulk)
- Target users with email and in-app campaigns
- Update subscription information
- Update the shopping cart and track purchases
- Register device and browser tokens
For example, you can call POST /api/users/update
with
a request body such as:
{ "email": "user@example.com", "dataFields": { "favoriteColor": "red" } }
For this request:
If your project doesn't yet have a user with an
email
address ofuser@example.com
, Iterables creates one.Then, whether the user is new or already exists, Iterable sets their
favoriteColor
tored
.
Creating new users when email is unknown
To create a new user for someone with an unknown email address (in an email-based
project), provide a userId
instead of an email
.
For example, you can call POST /api/users/update
.
In the request, body:
- Don't include an
email
. - Include a unique
userId
(one that doesn't yet exist in the Iterable project). - Set
preferUserId
totrue
, which tells the API to create a new user if the provideduserId
doesn't yet exist in the project.
For example:
{ "userId": "user1234567", "preferUserId": true, "dataFields": { "favoriteColor": "red" } }
For this request:
If your project doesn't have a user with a
userId
ofuser1234567
, Iterable creates one.Since this is an email-based project, Iterable assigns the user a unique
email
with a@placeholder.email
domain. This is just a unique identifier, not a way to contact the user.Then, whether the user is new or already exists, Iterable sets the user's
favoriteColor
tored
.
In subsequent API calls, you can identify this user by their userId
, or by the
placeholder email
given to them by Iterable.
Assigning a userId to an existing user
In an email-based project, you can also assign a userId
to an existing user
who is already identified by email
.
For example, you can call POST /api/users/update
.
In the request body:
- For
email
, specify the existing user's email address. - In
dataFields
, provide auserId
.
For example:
{ "email": "existingUser@example.com", "dataFields": { "userId": "newUserId" } }
For this request:
- Iterable checks to see whether your project already has a user with
email
set toexistingUser@example.com
. It not, the user is created. - Whether the user is new or already exists, Iterable assigns a
userId
ofnewUserId
to the user.
WARNING
In email-based projects, when assigning a userId
to an existing user, Iterable
does not verify that the specified userId
hasn't already been used in your
project. If you reuse a userId
on multiple users in the same project, it can
lead to unpredictable results: Iterable can't guarantee which user will be
affected by an API call that references a userId
assigned to multiple users.
UserID-based projects
UserID-based projects identify users by userId
. As you create users and give
them each a userId
, Iterable enforces userId
uniqueness. userId
values can
be a maximum of 52 characters, and they're case-sensitive.
TIP
UserID-based is often the most sensible type of project to choose, because these projects:
- Are simple to use. You always identify users by
userId
. - Allow you to match Iterable
userId
values with user identifiers you use in other systems. - Allow multiple users to share the same email address, which can sometimes be useful.
In userID-based projects, email
is not a user identifier. You can assign
email
addresses to your users (just like you can assign any other field, like
favoriteColor
), but you can't use email
to look up or modify users (in
Iterable's web UI or when making API calls). Since, in userID-based projects,
email
is a field just like any other, multiple users can have the same email
address.
TIP
When calling the GDPR forget and unforget endpoints in a userID-based project,
you must use userId
, not email
.
Creating new users in userID-based projects
In userID-based projects, when you make an API request that includes a userId
not yet used by your project, some endpoints create new users:
- Update user data (individually or in bulk)
- Target users with email and in-app campaigns
- Update subscription information
- Update the shopping cart and track purchases
- Register device and browser tokens
- Track events (individually or in bulk)
- Trigger workflows
NOTE
In API calls to userID-based projects, the API ignores the preferUserId
parameter that's sometimes used in API calls to email-based projects. There's no
need to include this parameter.
For example, call POST /api/users/update
, with a
request body such as:
{ "userId": "user1234567", "dataFields": { "favoriteColor": "red" } }
For this request:
- If there's no user with
userId
set touser1234567
, Iterable creates one. - Whether the user is new or already exists, Iterable sets their
favoriteColor
tored
.
Email in userID-based projects
You can assign an email
to each user in a userID-based project.
NOTE
Since email
is not a required field in userID-based projects, Iterable does
not automatically assign @placeholder.email
addresses like it does in
email-based projects.
To do this, call POST /api/users/update
, with a
request body such as:
{ "userId": "user1234567", "dataFields": { "email": "user@example.com" } }
For this request:
If there's no user with
userId
set touser1234567
, Iterable creates one.-
Whether the user is new or already exists, Iterable sets their
email
touser@example.com
.NOTE
In userID-based projects, Iterable does not enforce
email
uniqueness. This allows you to give the sameemail
to many users in the same project, which can sometimes be useful.
Hybrid projects
Hybrid projects identify users by email
, by userId
, or by both of these
values. In these projects, Iterable enforces uniqueness on both of these fields,
but it does not automatically assign them.
To identify a user in an API call to a hybrid project, add a userId
or an
email
(but not both) to the top level of your API request (outside of
dataFields
). If you provide both, userId
takes precedence.
Since email
is not a required field in hybrid projects, Iterable does not
assign @placeholder.email
addresses like it does in email-based projects.
TIP
When calling the GDPR forget and unforget endpoints in a hybrid project, you can
use either userId
or email
.
Creating new users in hybrid projects
In hybrid projects, when you make an API request that references a non-existent
userId
or email
, some endpoints create new user profiles:
- Update user data (individually or in bulk)
- Target users with email and in-app campaigns
- Update subscription information
- Update the shopping cart and track purchases
- Register device and browser tokens
- Track events (individually or in bulk)
- Trigger workflows
For example, you can call POST /api/users/update
with a request body such as:
{ "email": "user@example.com", "dataFields": { "favoriteColor": "red" } }
For this request:
- If there's no user with an
email
ofuser@example.com
, Iterable creates one. - Whether the user is new or already exists, Iterable sets their
favoriteColor
tored
.
Another example request:
{ "userId": "user1234567", "dataFields": { "favoriteColor": "red" } }
For this request:
- If there's no user with a
userId
ofuser1234567
, Iterable creates one. - Whether the user is new or already exists, Iterable sets their
favoriteColor
tored
.
NOTE
In userID-based projects, Iterable's API ignores the preferUserId
parameter
used in email-based projects for some endpoints.
email
and userId
precedence (by project type)
Generally, API requests should identify specific users by email
or userId
,
but not both, at the top level (outside of dataFields
). If a request does
include both fields, precedence rules apply.
For example, consider this request to POST /api/users/update
:
{ "email": "user@example.com", "userId": "user1234567", "dataFields": { "favoriteColor": "red" } }
In an email-based project,
email
anduserId
are both valid user identifiers. However,email
takes precedence, since it's guaranteed to be unique. So, for this request, in an email-based project, Iterable looks up or creates a user withemail
addressuser@example.com
. Then, it sets theirfavoriteColor
tored
.-
In a userID-based project,
userId
is the only valid user identifier, and it's guaranteed to be unique. So, for this request, in a userID-based project, Iterable looks up or creates a user with auserId
ofuser1234567
. Then, it sets theirfavoriteColor
tored
.As a convenience for this request, Iterable also sets the user's
email
touser@example.com
. However, sinceemail
is not a user identifier in userID-based projects, the API does not verify its uniqueness. -
In a hybrid project,
userId
andemail
are both valid user identifiers that are guaranteed to be unique. However,userId
takes precedence. So, Iterable interprets this request to mean, "Find or create a user with auserId
ofuser1234567
, and set theirfavoriteColor
tored
."As a convenience for this request, Iterable also attempts to set the user's
email
touser@example.com
(even though that value is specified outside ofdataFields
.) However, since hybrid projects enforce uniqueness onemail
, Iterable first checks whether or not the project already has a user with anemail
ofuser@example.com
.If
user@example.com
is not yet in use, the request succeeds. Iterable creates or updates a user with auserId
ofuser1234567
, settingemail
touser@example.com
andfavoriteColor
tored
.If
user@example.com
is already in use, the entire request fails with an HTTP status code409
. You can't reuse an email address that already belongs to another user.
Comments
0 comments
Please sign in to leave a comment.