API Overview and Sample Payloads

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

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 or Api_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.

# 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

• EU-based Iterable projects

  • Base URL: https://api.eu.iterable.com
  • For example: https://api.eu.iterable.com/api/events/track

# 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 or userId. However, Iterable only enforces email uniqueness, not userId.

• UserID-based projects identify users by userId, and Iterable enforces the uniqueness of this field.

• Hybrid projects projects identify users by email and/or userId, and Iterable enforces the uniqueness of both. However, you don't have to give both fields to every user.

# 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 a userId or an email (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 and userId at the top level of an API request, precedence rules apply.

  Some requests require you to place userId or email inside another object, rather than at the top level of your API request. For example, when calling POST /api/commerce/updateCart, you need to place userId or email inside a user object.

  Additionally, some requests use slightly different field names. For example, POST /api/email/target requires recipientEmail and recipientUserId, rather than email and userId. 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 of user1234567, Iterable creates one.

• Then, whether the user is new or already exists, Iterable sets their favoriteColor to red.

If this request is sent to an email-based project:

• If there's already a user identified by a userId of user1234567, Iterable updates their favoriteColor to red.

• Otherwise, the request fails. (To create a new user by userId in an email-based project, your request must set preferUserId to true. Since email is required in email-based projects, setting preferUserId to true 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 and pageSize 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 and nextPageUrl values (as applicable). Use these to load more data.

• If you specify a page and pageSize combination outside the range of available data, the API 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 the price field (set to 45000).

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 and pageSize in the query string to specify a page number and page size. For example:

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

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

• If you specify a page and pageSize combination outside the range of available data, the API 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 and string

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

On success, this API returns HTTP status code 200.

# 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 a firstName field and a lastName field. The above request body specifies that previousOwner is an object while its children, firstName and lastName, are strings.

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

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

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

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.

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.

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.

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

# Email

# 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.

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:

• GET /api/export/data.csv
• GET /api/export/data.json
• GET /api/export/userEvents

For higher-volume requests (up to 100GB), use Iterable's async export APIs:

• POST /api/export/start
• GET /api/export/{jobId}/files
• DELETE /api/export/{jobId}

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

# 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, provide text/csv or application/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 using GET /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 type 12345:

  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 type 12345:

  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 type 12345:

  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 type 12345:

  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, use action=unsubscribe.

• For subscriptionGroup, provide one of the following values:

  • messageChannel
  • messageType
  • emailList

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

• For the request body, provide a users array containing the email addresses of the users to subscribe or unsubscribe, and/or a usersByUserId array containing the userId 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, and user1234567 to message type 12345:

  PUT https://api.iterable.com/api/subscriptions/messageType/12345
  

  Request body:

  {
    "users": [
      "user@example.com",
      "user2@example.com"
    ],
    "usersByUserId": [
      "user1234567"
    ]
  }
  

# Templates

# 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.

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

# 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

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, not userId.
• In userID-based projects, you must forget and unforget users by userId, not email.
• In hybrid projects, you can forget and unforget users by email or userId (and you can use one identifier to forget, and the other to unforget).

# 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, not userId.
• In userID-based projects, you must forget and unforget users by userId, not email.
• In hybrid projects, you can forget and unforget users by email or userId (and you can use one identifier to forget, and the other to unforget).

# DELETE /api/users/{email}

Delete a user by email
API reference: US-based projects, EU-based projects

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 set preferUserId to true .
• 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).

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.

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.

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.

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.

# 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.

# 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 of user@example.com, Iterables creates one.

• Then, whether the user is new or already exists, Iterable sets their favoriteColor to red.

# 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 to true, which tells the API to create a new user if the provided userId 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 of user1234567, 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 to red.

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 a userId.

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 to existingUser@example.com. It not, the user is created.
• Whether the user is new or already exists, Iterable assigns a userId of newUserId to the user.

# 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.

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.

# 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

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 to user1234567, Iterable creates one.
• Whether the user is new or already exists, Iterable sets their favoriteColor to red.

# Email in userID-based projects

You can assign an email to each user in a userID-based project.

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 to user1234567, Iterable creates one.

• Whether the user is new or already exists, Iterable sets their email to user@example.com.

  NOTE

  In userID-based projects, Iterable does not enforce email uniqueness. This allows you to give the same email 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.

# 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 of user@example.com, Iterable creates one.
• Whether the user is new or already exists, Iterable sets their favoriteColor to red.

Another example request:

POST /api/users/update

{
  "userId": "user1234567",
  "dataFields": {
     "favoriteColor": "red"
  }
}

For this request:

• If there's no user with a userId of user1234567, Iterable creates one.
• Whether the user is new or already exists, Iterable sets their favoriteColor to red.

# 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 and userId 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 with email address user@example.com. Then, it sets their favoriteColor to red.

• 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 a userId of user1234567. Then, it sets their favoriteColor to red.

  As a convenience for this request, Iterable also sets the user's email to user@example.com. However, since email is not a user identifier in userID-based projects, the API does not verify its uniqueness.

• In a hybrid project, userId and email 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 a userId of user1234567, and set their favoriteColor to red."

  As a convenience for this request, Iterable also attempts to set the user's email to user@example.com (even though that value is specified outside of dataFields.) However, since hybrid projects enforce uniqueness on email, Iterable first checks whether or not the project already has a user with an email of user@example.com.

  If user@example.com is not yet in use, the request succeeds. Iterable creates or updates a user with a userId of user1234567, setting email to user@example.com and favoriteColor to red.

  If user@example.com is already in use, the entire request fails with an HTTP status code 409. You can't reuse an email address that already belongs to another user.

# Further reading

• API Keys
• API reference docs (US-based projects)
• API reference docs (EU-based projects)