Iterable API Endpoints and Sample Payloads

Use Iterable's API to interact with a project's users, templates, campaigns, journeys, and more. This article describes how to use each of Iterable's API endpoints, and provides sample payloads.

# Iterable's API endpoints

# Campaigns

# GET /api/campaigns

List campaign metadata
API reference: USDC-based projects, EDC-based projects

Retrieves metadata about the campaigns in the project associated with the API key (for example, id, createdAt, name, templateId, etc.).

When a campaign has labels:

• The response includes both labels (an array of strings) and labelIds (an array of integers), which can hold one or more values.
• The order of labels and labelIds are not indexed to match positionally. The first label name in the labels array doesn't always correspond to the first label ID in the labelIds array, and vice versa.
• To identify a label by its ID, go to the Project Settings page.

Sample JSON response:

{
  "campaigns": [
    {
      "id": 59530,
      "createdAt": 1475452500507,
      "updatedAt": 1475452500591,
      "startAt": 1475535300000,
      "endedAt": 1475542440016,
      "name": "Example campaign #1",
      "templateId": 93661,
      "createdByUserId": "user@example.com",
      "campaignState": "Finished",
      "messageMedium": "Email",
      "listIds": [
        16182
      ],
      "suppressionListIds": [],
      "sendSize": 3,
      "labelIds": [
        12345,
        67890
      ],
      "labels": [
        "newsletter",
        "2025_Q1"
      ]
    },
    {
      "id": 59355,
      "createdAt": 1475265000217,
      "updatedAt": 1475265000276,
      "startAt": 1475265000274,
      "endedAt": 1475265000320,
      "name": "Example campaign #2",
      "templateId": 93419,
      "createdByUserId": "user@example.com",
      "campaignState": "Finished",
      "messageMedium": "Email",
      "listIds": [
        14007
      ],
      "suppressionListIds": [],
      "sendSize": 3,
      "labelIds": [],
      "labels": []
    }
  ]
}

# GET /api/campaigns/{id}

Get campaign details
API reference: USDC-based projects, EDC-based projects

Retrieves detailed information about a specific campaign by its ID.

When a campaign has labels, the response includes both labels (label names) and labelIds (label IDs).

Sample JSON response:

{
  "id": 59530,
  "createdAt": 1475452500507,
  "updatedAt": 1475452500591,
  "startAt": 1475535300000,
  "endedAt": 1475542440016,
  "name": "Example campaign #1",
  "templateId": 93661,
  "createdByUserId": "user@example.com",
  "campaignState": "Finished",
  "messageMedium": "Email",
  "listIds": [
    16182
  ],
  "suppressionListIds": [],
  "sendSize": 3,
  "labelIds": [
    12345
  ],
  "labels": [
    "newsletter"
  ],
  "dataFields": {
    "customField": "value"
  },
  "sendMode": "Immediate",
  "recipientTimeZone": {
    "defaultTimeZone": "America/New_York",
    "startTimeZone": "America/New_York"
  }
}

# POST /api/campaigns/abort

Abort a campaign
API reference: USDC-based projects, EDC-based projects

Abort a campaign, given a campaign ID.

# POST /api/campaigns/{campaignId}/schedule

Schedule a campaign
API reference: USDC-based projects, EDC-based projects

Schedules the send of a campaign, given its campaignId (as a path parameter).

Use this endpoint to schedule a blast campaign that is in the Ready state. This request places the campaign in the Scheduled state.

Sample request body:

{
    "sendAt": "2024-09-15T00:00:00Z",
    "recipientTimeZone": {
        "defaultTimeZone": "America/Denver",
        "startTimeZone": "America/New_York"
    }
}

# POST /api/campaigns/activateTriggered

Activate a triggered campaign
API reference: USDC-based projects, EDC-based projects

Activates a triggered campaign, given its campaignId (in the request body).

Use this endpoint to change an API-triggered campaign from the Ready state to the Running state.

Sample request body:

{
  "campaignId": 12345
}

To learn more about activating and sending triggered campaigns, read Activating a Triggered Campaign.

# POST /api/campaigns/archive

Archive campaigns
API reference: USDC-based projects, EDC-based projects

Archives one or more campaigns. This endpoint behaves the same as the archive feature in the UI. Scheduled or recurring campaigns are cancelled, and running campaigns are aborted.

Archived campaigns are hidden from the Campaigns page, but can still be viewed in the Archived tab.

Sample request body:

{
  "campaignIds": [
    12345,
    12346
  ]
}

# POST /api/campaigns/cancel

Cancel a scheduled or recurring campaign
API reference: USDC-based projects, EDC-based projects

Cancel a campaign, given a campaign ID.

# POST /api/campaigns/create

Create a new campaign
API reference: USDC-based projects, EDC-based projects

Use this endpoint to create a new blast or triggered campaign from an existing template. This endpoint can create email, push notification, web push notification, SMS, and in-app message campaigns. It can't create embedded message campaigns. Global suppression lists are not automatically applied to campaigns created by this endpoint. If you want to apply a global suppression list to a campaign created with this endpoint, include the list ID in the suppressionListIds request parameter.

The new campaign receives a copy of the template specified by templateId. Because it's a copy, the campaign's templateId won't match the templateId specified in the request, and edits to the campaign's template will not affect the original template.

To associate existing labels with the new campaign, include labelIds in the request body. labelIds must contain label IDs from the same project, and you can include up to 50 label IDs. You can find the ID for each label in the Project Settings page.

# Creating a triggered campaign

To create a triggered campaign:

• In the request body, specify a name and templateId. Add dataFields as needed.
• Omit listIds from the request body.

The new triggered campaign will be in the Ready state. Before the campaign can start sending, activate it using the POST /api/campaigns/activateTriggered endpoint or in the Iterable UI.

To learn more about activating and sending triggered campaigns, read Activating a Triggered Campaign.

Sample request body:

{
  "name": "Sample Triggered Campaign",
  "templateId": 28533
}

# Creating a blast campaign that sends immediately

To create a blast campaign that sends immediately to all specified recipients:

• In the request body, specify a name and templateId. Add dataFields as needed.
• Omit sendAt from the request body.
• Set listIds to an array of list IDs to which Iterable should send the campaign.
• If necessary, specify suppressionListIds, too.

Sample request body:

{
  "name": "Sample Blast Campaign",
  "templateId": 28533,
  "listIds": [
    5925,
    6094
  ],
  "suppressionListIds": [
    6095
  ]
}

# Creating a campaign with labels

To create a blast or triggered campaign with labels, include labelIds in the request body. Labels must already exist in the project, and you can include up to 50 label IDs. You can find the ID for each label in the Project Settings page.

Sample request body:

{
  "name": "Sample Blast Campaign",
  "templateId": 28533,
  "listIds": [
    5925,
    6094
  ],
  "labelIds": [
    12345,
    67890
  ]
}

# Creating a blast campaign scheduled for a future time

To create a blast campaign scheduled to send simultaneously to all specified recipients at a specific future time:

• In the request body, specify a name and templateId. Add dataFields as needed.
• Set listIds to an array of list IDs to which Iterable should send the campaign.
• If necessary, specify suppressionListIds.
• Set sendAt to a UTC time in format YYYY-MM-DD HH:MM:SS, to indicate when Iterable should send the campaign. For send times in the past, Iterable sends the campaign immediately.

Sample request body:

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

# Creating a scheduled blast campaign for a future time (based on recipient time zone)

To create a blast campaign scheduled to send to each recipient at a specific local time in their own time zone:

• In the request body, specify a name and templateId. Add dataFields as needed.
• Set listIds to an array of list IDs to which Iterable should send the campaign.
• If necessary, specify suppressionListIds.
• Set sendMode to RecipientTimeZone.
• Set startTimeZone to the first time zone that should receive the campaign at the specified time.
  • Recipients in time zones to the east of startTimeZone receive the campaign at the same moment in time as recipients in startTimeZone.
  • Recipients in time zones to the west of startTimeZone receive the campaign when their local time matches the local time at which users received the campaign in startTimeZone.
• Set defaultTimeZone to the time zone to use for sending to recipients whose time zone is unknown. Use a value such as America/New_York.
• Set sendAt to a UTC time in format YYYY-MM-DD HH:MM:SS, up to 21 days in the future.
  • Iterable uses the local time in startTimeZone at sendAt as the campaign's local send time in all time zones, starting with startTimeZone and moving west.
  • For example, if sendAt represents 4:00pm in startTimeZone, Iterable sends the campaign at 4:00pm in startTimeZone, and at 4:00pm in time zones to the west of startTimeZone, too.
  • Recipients in time zones east of startTimeZone receive the message at the same moment in time as recipients in startTimeZone.
• If, when using RecipientTimeZone, you specify a past send time:
  • Recipients in startTimeZone, and time zones to the east of startTimeZone, receive the campaign immediately.
  • Recipients in time zones to the west of the startTimeZone receive the campaign when their local time matches the current local time in startTimeZone.

For example, to send a campaign on March 20th, 2024, at 4:00pm local time in all time zones starting with America/Denver:

• In the request body, Specify a name and templateId. Add dataFields as needed.
• Specify lists and suppression lists.
• Set sendMode to RecipientTimeZone.
• Set startTimeZone toAmerica/Denver.
• Set defaultTimeZoneto America/Denver (or whatever time zone you'd like to use for recipients without a time zone).
• Set sendAt to 2024-03-20 22:00:00 .
  • This UTC time is 4:00pm in the startTimeZone, which we set to America/Denver.
  • Therefore, the campaign will send at 4:00pm local time in time zones to the west of America/Denver, too.

Sample request body:

{
  "name": "Sample Blast Campaign",
  "templateId": 28533,
  "listIds": [
    5925,
    6094
  ],
  "suppressionListIds": [
    6095
  ],
  "sendMode": "RecipientTimeZone",
  "startTimeZone": "America/Denver",
  "defaultTimeZone": "America/Denver",
  "sendAt": "2024-03-20 22:00:00"
}

In this example:

• Recipients in New York (east of Denver, the starting time zone) receive the campaign at 4:00pm Denver time, which is 6:00pm local time in New York.
• Recipients in Denver receive the campaign at 4:00pm local time in Denver.
• Recipients in Los Angeles receive the campaign at 4:00pm local time in Los Angeles.
• Recipients without a timeZone field on their user profiles receive the campaign at 4:00pm Denver time, since Denver is the default time zone.

# POST /api/campaigns/deactivateTriggered

Deactivate a triggered campaign
API reference: USDC-based projects, EDC-based projects

Deactivates a triggered campaign, given its campaignId (in the request body).

Use this endpoint to change an API-triggered campaign from the Running state to the Finished state.

Sample request body:

{
  "campaignId": 12345
}

To learn more about activating and sending triggered campaigns, read Activating a Triggered Campaign.

# GET /api/campaigns/metrics

Get metrics for campaigns
API reference: USDC-based projects, EDC-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/recurring/{id}/childCampaigns

Get child campaigns of a recurring campaign
API reference: USDC-based projects, EDC-based projects

Retrieves metadata about campaigns (for example, id, createdAt, name, templateId, etc.)., in the project associated with the API key, that were generated by a recurring campaign.

Sample:

GET https://api.iterable.com/api/campaigns/recurring/12345/childCampaigns

Sample JSON response excerpt:

{
  "campaigns": [
    {
      "id": 12346,
      "name": "Example recurring campaign send",
      "messageMedium": "Email",
      "labelIds": [12345],
      "labels": ["newsletter"]
    }
  ]
}

# POST /api/campaigns/trigger

Trigger a campaign
API reference: USDC-based projects, EDC-based projects

Triggers the send of a campaign to a specific user or list of users. This endpoint can be used to:

• Send a blast campaign to a specific user or list of users.
• Trigger the send of a triggered campaign to a specific user or list of users.

To learn more about activating and sending triggered campaigns, read Activating a Triggered Campaign.

# POST /api/campaigns/{campaignId}/send

Send existing campaign now
API reference: USDC-based projects, EDC-based projects

Sends an existing campaign immediately. This endpoint can be used to send a campaign that is in the Ready state.

Sample JSON response:

{
  "success": true,
  "messageId": "12345"
}

# Catalogs

# GET /api/catalogs

Get catalog names
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-based projects

Deletes a catalog and all its items. This cannot be undone.

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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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

Commerce APIs allow you to track user purchases and update shopping carts. To learn more about how to use these APIs, read Managing Commerce Events and Shopping Cart Items

# POST /api/commerce/updateCart

Update a user's shopping cart items
API reference: USDC-based projects, EDC-based projects

Updates shoppingCartItems field on the user profile.

This endpoint's 2XX response indicates when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields. To learn more about this setting, read Data Schema Management Overview.

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: USDC-based projects, EDC-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.

This endpoint's 2XX response indicates when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields. To learn more about this setting, read Data Schema Management Overview.

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. The generated id should be stored for use in subsequent event updates.

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": "123 Main St",
    "shippingAddress2": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": 94107
  }
}

Sample response where an id of "12345" is passed in the track request:

{
    "msg": "Event with id: 12345 tracked.",
    "code": "Success",
    "params": {
        "id": "12345"
    }
}

Sample response when no id is passed in the track request:

{
    "msg": "Event with id: 1397b147db9c41f187a39844beba9c tracked.",
    "code": "Success",
    "params": {
        "id": "1397b147db9c41f187a39844beba9c"
    }
}

# Email

# POST /api/email/cancel

Cancel an email to a user
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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

# Embedded Messaging

# GET /api/embedded-messaging/messages

Get a user's embedded messages
API reference: USDC-based projects, EDC-based projects

This endpoint returns embedded messages for which the specified user is eligible, grouped by placementId. A user is eligible if they're selected by the dynamic list that's associated with the message's Iterable campaign.

By default, this endpoint returns data for all placements that have messages for the user. To constrain the response to specific placements, provide one or more placementId query parameters.

Sample request:

GET https://api.iterable.com/api/embedded-messaging/messages?email=user@example.com

Sample response body:

{
  "placements": [
    {
      "embeddedMessages": [
        {
          "elements": {
            "body": "Tell us how we're doing. Take our survey!",
            "buttons": [
              {
                "action": {
                  "data": "https://example.com/survey",
                  "type": "openUrl"
                },
                "id": "surveyButton",
                "title": "Take survey"
              }
            ],
            "defaultAction": {
              "data": "https://example.com/",
              "type": "openUrl"
            },
            "mediaUrl": "https://example.com/images/example.png",
            "mediaUrlCaption": "Take our survey!",
            "text": [
              {
                "id": "",
                "label": "color",
                "text": "#FF0000"
              }
            ],
            "title": "Take our survey!"  
          },
          "metadata": {
            "campaignId": 1234567,
            "isProof": false,
            "messageId": "...",
            "placementId": 0,
            "priorityOrder": 0
          },
          "payload": {}
        }
      ],
      "placementId": 202
    }
  ]
}

Every embedded message returned by this endpoint has a metadata object, including messageId, placementId, campaignId, and isProof fields. Other fields are present in the API response only if they have data.

# Events

# POST /api/embedded-messaging/events/session

Track an embedded message session and related impressions
API reference: USDC-based projects, EDC-based projects

This endpoint tracks a single embeddedSession event, and one embeddedImpression event for each of the session's impressions.

An embeddedSession event represents a period of time when a user is viewing a page or a screen where embedded messages can be displayed (in one or many placements).

An embeddedImpression event represents the number of times a given embedded message was visible during the session, and the total amount of time the message was visible (in seconds) across all those appearances.

This endpoint does not create events for test messages (proofs).

Learn about identifying users in API requests.

Sample request:

POST https://api.iterable.com/api/embedded-messaging/events/session

{
  "email": "user@example.com",
  "session": {
     "id": "...",
     "start": 1699424658,
     "end": 1699424778
  },
  "impressions": [
    {
      "messageId": "...",
      "placementId": 0,
      "displayCount": 3,
      "displayDuration": 25
    },
    {
      "messageId": "...",
      "placementId": 0,
      "displayCount": 2,
      "displayDuration": 15
    }
  ],
  "deviceInfo": {
    "deviceId": "...",
    "platform": "iOS",
    "appPackageName": "com.example.app"
  },
  "createdAt": 1699424800
}

Include a userId or email, but not both. createdAt is an optional Unix timestamp that indicates when the event was created (if not provided, it's assigned the time that Iterable receives the event).

# POST /api/embedded-messaging/events/received

Track an embedded message received event
API reference: USDC-based projects, EDC-based projects

This endpoint tracks that a given embedded message was received on a device. It creates an embeddedReceived event in Iterable.

An embeddedReceived event indicates that a device has retrieved a message. It does not mean that the message has been displayed.

Iterable's SDKs automatically call this endpoint for each embedded message they retrieve. If you're not using an SDK, call this endpoint once per embedded message you retrieve from Iterable's API.

For test messages (proofs), no events are created.

Learn about identifying users in API requests.

Sample request:

POST https://api.iterable.com/api/embedded-messaging/events/received

{
  "email": "user@example.com", 
  "messageId": "...",
  "deviceInfo": {
    "deviceId": "...",
    "platform": "iOS",
    "appPackageName": "com.example.app"
  },
  "createdAt": 1699424800
}

Include a userId or email, but not both. createdAt is an optional Unix timestamp that indicates when the event was created (if not provided, it's assigned the time that Iterable receives the event).

# POST /api/embedded-messaging/events/click

Track an embedded message click
API reference: USDC-based projects, EDC-based projects

This endpoint tracks a click on an embedded message. It creates an embeddedClick event.

For test messages (proofs), no events are created.

Learn about identifying users in API requests.

Sample request:

POST https://api.iterable.com/api/embedded-messaging/events/click

{
  "email": "user@example.com",
  "messageId": "...",
  "buttonIdentifier": "surveyButton",
  "targetUrl": "https://example.com/survey",
  "deviceInfo": {
    "deviceId": "...",
    "platform": "iOS",
    "appPackageName": "com.example.app"
  },
  "createdAt": 1699424800
}

Include a userId or email, but not both. createdAt is an optional Unix timestamp that indicates when the event was created (if not provided, it's assigned the time that Iterable receives the event).

# POST /api/events/inAppConsume

Consume or delete an in-app message
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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 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.

This endpoint's 2XX response indicates when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields. To learn more about this setting, read Data Schema Management Overview.

Sample request body:

{
  "email": "user@example.com",
  "eventName": "startedMembership",
  "id": "12345",
  "dataFields": {
    "source": "facebook",
    "membershipType": "monthly"
  },
  "userId": "1",
  "campaignId": 123,
  "templateId": 123,
  "createNewFields": true
}

In this example, source is an unrecognized data field.

Sample response body:

{
  "msg": "Event with id: f8bc79gghh47f45798b00032de21a12cf2 tracked. Fields that were created were: [startedMembership.source]",
  "code": "Success",
  "params": {
    "id": "f8bc79eebb9d4d98ba3e32d000d67dmf2"
  }
}

# POST /api/events/trackWebPushClick

Track a web push click
API reference: USDC-based projects, EDC-based projects

Learn about identifying users in API requests.

# POST /api/events/trackPushOpen

Track a mobile push open
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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.

Important notes:

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

This endpoint's 2XX response indicates when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields. To learn more about this setting, read Data Schema Management Overview.

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: USDC-based projects, EDC-based projects

Exports experiment metrics as CSV. This endpoint returns data only for email experiments. You can:

• Provide multiple experimentId and/or campaignId query parameters (up to 200 total per request).
• Optionally pass startDateTime and/or endDateTime to limit results to experiments that overlap the provided window.
• Omit IDs to fetch metrics for all experiments in the project (up to the same 200-experiment limit).

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 high volume requests (up to 100GB), use Iterable's asynchronous 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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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": [  // Note: This could be "userListIds" depending on project type
    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: USDC-based projects, EDC-based projects

Starts a data export. The export processes as a background job.

Required parameters:

• outputFormat - Type of output file: text/csv or application/x-json-stream.

• dataTypeName - Type of data to export (list must be comma-separated with no spaces between item 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 parameters:

• startDateTime - The start of the period. Inclusive. Use any date format supported by Iterable.
• endDateTime - The end of the period to export. Exclusive. Use any date format supported by Iterable.
• omitFields - Fields to omit from the export (comma-separated).
• onlyFields - Only include these fields in the export (comma-separated). This parameter limits the export columns explicitly to what's listed. It doesn't filter out null values.

• campaignId - The campaign to export data for.
• delimiter - CSV file delimiter, default is , (comma).

Save the returned jobId to check job status and retrieve export files using GET /api/export/{jobId}/files.

Concurrent request limit: Iterable simultaneously processes up to 4 jobs per organization. Additional jobs are queued for processing later.

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: USDC-based projects, EDC-based projects

Gets the job status and links for exported files with the POST /api/export/start endpoint.

Job states can be enqueued, running, completed, or failed. Occasionally, a job status may change from running to enqueued because it had to restart. When this happens, the job maintains progress and begins where it previously stopped. Iterable uses an exponential backoff pattern for retries—when Iterable has had to retry a job several times, the delay is progressively longer.

Exports are limited to 100GB in total size, with files up to 10MB each.

Files are added to the list as the export job is running. 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 30 minutes, and after that time you must request new links. After seven 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

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: USDC-based projects, EDC-based projects

Cancels a queued or running export created with the POST /api/export/start endpoint.

# GET /api/export/jobs

Get export jobs
API reference: USDC-based projects, EDC-based projects

Returns a list of recent export jobs for the current project. Only includes jobs for the current project and not other projects.

Optional parameters:

• jobState - Filter results to only include jobs in the specified state (enqueued, queued, running, completed, failed, cancelled, cancelling)

Sample JSON response:

{
  "jobs": [
    {
      "id": 3562,
      "dataTypeName": "user",
      "jobState": "completed",
      "scheduledStartTime": "2023-12-19T10:12:27.732-06:00",
      "endTime": "2023-12-19T10:12:28.214-06:00",
      "bytesExported": 2453629
    }
  ]
}

# In-app messages

# GET /api/inApp/getPriorityMessage

Get a user's most relevant in-app message
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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)

# GET /api/journeys

Get all journeys in the project
API reference: USDC-based projects, EDC-based projects

This endpoint returns an array of journeys that exist in the Iterable project associated with the API key found in the request.

• By default, this endpoint returns all non-archived journeys. To fetch archived journeys instead, set the state query parameter to Archived.

• To sort results, use the sort query parameter. The default sort order is id (ascending). Change sort order with optional direction prefix: use - for descending, + or no prefix for ascending. Examples: -createdAt, +name.

• To page results, use these query parameters:

  • page – The page number to return. Default is 1.
  • pageSize – The number of journeys to return in each page. Default is 10, maximum is 50.

Sample request:

https://api.iterable.com/api/journeys?page=1&pageSize=50&state=Archived

Sample response body:

{
    "journeys": [
        {
            "id": 123456,
            "createdAt": 1623962210749,
            "updatedAt": 1623962210754,
            "name": "Example archived workflow #1",
            "journeyType": "Published",
            "creatorUserId": "user@example.com",
            "enabled": false,
            "startTileId": 2004669,
            "triggerEventNames": [
                "apiTrigger"
            ],
            "isArchived": true,
            "description": ""
        },
        {
            "id": 123499,
            "createdAt": 1629132761167,
            "updatedAt": 1629132764980,
            "name": "Example archived workflow #2",
            "journeyType": "Published",
            "creatorUserId": "user@example.com",
            "enabled": false,
            "startTileId": 2215538,
            "triggerEventNames": [
                "apiTrigger"
            ],
            "isArchived": true,
            "description": ""
        }
    ],
    "totalJourneysCount": 2
}

# POST /api/workflows/triggerWorkflow

Trigger a workflow
API reference: USDC-based projects, EDC-based projects

Triggers a journey for a single user and/or all users on a list. Works for both static 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: USDC-based projects, EDC-based projects

Deletes a list. All users who are part of the deleted list have the list removed from their profile.

The list must not be in use. Attempting to delete a list in use will cause the request to fail with a 409 Conflict response code and a message indicating where the list is active.

Sample request:

https://api.iterable.com/api/lists/21398

# GET /api/lists

Get lists
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-based projects

Creates a new, empty, static 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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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/previewUsers

Preview users in a list
API reference: USDC-based projects, EDC-based projects

Returns a random sample of users from a static or dynamic list.

Accepted path parameters:

• listId (required) - The ID of the list to preview.
• size (optional, default is 1000, maximum is 5000) - The number of users to return. If the list has fewer users than the preview size requested, the API response includes all users.
• preferUserId (optional, default is false) - For Hybrid projects, set to true to return user IDs instead of email addresses. The list will return the user's email field if the user does not have a userId value. If the user has a userId value, the API response includes the user's userId value.

Sample request:

GET https://api.iterable.com/api/lists/previewUsers?listId=12345&size=5

Sample response (text/plain):

user1@example.com
user2@example.com
user3@example.com
user4@example.com
user5@example.com

# GET /api/lists/{listId}/size

Get count of users in list
API reference: USDC-based projects, EDC-based projects

Get the number of users within a list.

# Message types

# GET /api/messageTypes

List message types
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-based projects

Get the metadata value of a single key.

# PUT /api/metadata/{table}/{key}

Create or replace metadata
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-based projects

List keys in a given table.

# GET /api/metadata

List available tables
API reference: USDC-based projects, EDC-based projects

List available tables.

# Push notifications

# POST /api/push/cancel

Cancel a push notification to a user
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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"
}

# Snippets

Iterable's Snippets API allows you to create, retrieve, update, and delete snippets.

To learn more about snippets and how they work as reusable content, see Snippets Overview.

Here are some things to know when working with the Snippets API:

# Identifying snippets

Iterable identifies snippets by either their name or id. For endpoints that accept an identifier path parameter, you can use either the name or id value.

When you create a snippet, provide a unique name (string). Iterable assigns an id (numeric) for the snippet upon creation.

• Snippet name: Provide a name that is unique within the project. The name is a string up to 100 characters. Names are case-sensitive and can include letters (a-z, A-Z), numbers, hyphens (-), underscores (_), and spaces.

  You can use the snippet’s name to identify it in API requests and to reuse its content in a template.

  • Spaces in names: A snippet's name can contain spaces. When using the name to identify a snippet as a path parameter, you must URL-encode the name if it contains spaces. For example, if the snippet name is Welcome Banner, you would use Welcome%20Banner as the path parameter.

  • Numbers as names: You can use numbers in a snippet's name. However, if the name is just numbers (with no letters or other characters), you won't be able to use it to identify the snippet in API requests. This is because Iterable treats a numeric name as an id instead of a string, and may not find the correct snippet. In these cases, use the snippet's id (assigned by Iterable) to identify it in API requests.

  IMPORTANT

  Once you create a snippet, you can't change its name.

• Snippet ID: Iterable assigns a unique id for each snippet when it's created. Snippet IDs are integers.

  You can use this ID later to identify a snippet when updating or deleting it using the API.

# Snippet content

When a snippet is referenced in a template, the content is what displays to the user when Iterable renders the campaign. The content parameter is a string that can include HTML, CSS (inline styles), Handlebars expressions, and data feed references. Handlebars expressions must be valid, and a snippet can't reference itself.

• Content size: There isn't a specific size limit for content, however the total API request size cannot exceed 4MB.

  Keep in mind also that the content size is imported into the Iterable template and impacts the total size of the template. If you are also using Handlebars expressions in your content, the content size may be smaller or larger than the actual content you see in the snippet editor.

  TIP

  Snippet content size is important to be aware of when sending from certain channels. Here are a couple of examples of considerations for different channels:

  • For SMS, content size impacts the number of segments and snippets that are too long can have billing impacts for increased segments. To learn more about SMS segment limits, read SMS Segment Limits and Character Encoding.

  • For email, content size impacts the overall email size. Content bodies over 100KB can cause email message clipping in the user's inbox. To learn more, read Troubleshooting Message Clipping.

  When you are adding a snippet to a template, make sure you are aware of the content size limits for the channel you're sending to, and preview your campaigns with data before sending.

  If you're using variables, make sure to preview and/or test with different values for the variables to make sure the content size for all variations are within the limits for the channel you're sending to.

• Disallowed content:

  • Script tags with JavaScript sources or non-JSON content
  • Inline JavaScript event handlers (such as onload="...")
  • javascript: in href or src attributes (such as anchors and iframes)

# Variables in content

# GET /api/snippets

Get all snippets
API reference: USDC-based projects, EDC-based projects

Retrieves all snippets for the project, including all fields for each snippet.

Sample request:

GET https://api.iterable.com/api/snippets

Sample JSON response:

{
  "snippets": [
    {
      "id": 12345,
      "name": "Copyright_year",
      "content": "© 2025 Fiterable, Inc.",
      "description": "Copyright year snippet",
      "createdAt": "2025-01-01T10:00:00Z",
      "updatedAt": "2025-01-15T14:30:00Z",
      "createdBy": "user@example.com",
      "updatedBy": "user2@example.com",
      "projectId": 789
    },
    {
      "id": 12346,
      "name": "Welcome_Banner",
      "content": "<div style='background-color: {{bannerColor}};'>Welcome {{firstName}}!</div>",
      "description": "Welcome banner with customizable color",
      "variables": ["bannerColor", "firstName"],
      "createdAt": "2025-01-01T10:00:00Z",
      "updatedAt": "2025-01-15T14:30:00Z",
      "createdBy": "user1@example.com",
      "updatedBy": "user2@example.com",
      "projectId": 789
    },
    ...
  ]
}

# POST /api/snippets

Create a snippet
API reference: USDC-based projects, EDC-based projects

Creates a new snippet in the project.

Sample request body:

{
  "name": "Welcome_Banner",
  "content": "<div style='background-color: {{bannerColor}};'>Welcome {{firstName}}!</div>",
  "createdByUserId": "user@example.com",
  "description": "Welcome banner with customizable color",
  "variables": ["bannerColor", "firstName"]
}

Sample JSON response:

{
  "snippetId": 12346
}

# GET /api/snippets/{identifier}

Get snippet by ID or name
API reference: USDC-based projects, EDC-based projects

Retrieves a specific snippet by its id or name.

Sample requests:

GET https://api.iterable.com/api/snippets/12345

GET https://api.iterable.com/api/snippets/Welcome_Banner

Sample JSON response:

{
  "snippet": {
    "id": 12345,
    "name": "Welcome_Banner",
    "content": "<div style='background-color: {{bannerColor}};'>Welcome {{firstName}}!</div>",
    "description": "Welcome banner with customizable color",
    "variables": ["bannerColor", "firstName"],
    "createdAt": "2025-01-01T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "createdBy": "user1@example.com",
    "updatedBy": "user2@example.com",
    "projectId": 789
  }
}

# PUT /api/snippets/{identifier}

Create or update a snippet
API reference: USDC-based projects, EDC-based projects

Updates a snippet if it already exists, or creates a new one if it doesn't.

• If you provide an id, the endpoint only updates an existing snippet with that ID. If no snippet with that ID exists, you'll get an error.
• If you provide a name, the endpoint updates a snippet with that name. If no snippet with that name exists, it creates a new snippet.

A successful update returns a 200 status code. If a new snippet is created, Iterable returns a 201 status code.

Sample request body:

{
  "content": "<div style='background-color: {{bannerColor}};'>Welcome {{capitalize firstName}}!</div>",
  "description": "Updated welcome banner with customizable color",
  "variables": ["bannerColor", "firstName"]
}

Sample JSON response:

{
  "snippetId": 12346
}

# DELETE /api/snippets/{identifier}

Delete a snippet
API reference: USDC-based projects, EDC-based projects

Deletes a snippet by its numeric ID or string name.

Sample requests:

DELETE https://api.iterable.com/api/snippets/12345

DELETE https://api.iterable.com/api/snippets/Welcome_Banner

Sample JSON response:

{
  "snippetId": 12345
}

# Subscriptions

The following APIs manage user subscriptions to message channels, message types, and email lists.

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

Unsubscribe a single user
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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.

• If you're subscribing a user to a double opt-in message type, the user skips the SMS Double Opt-In flow and is immediately subscribed to the message type. To engage a user in the SMS Double Opt-In flow, use the POST /api/subscriptions/subscribeToDoubleOptIn endpoint.

• 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: USDC-based projects, EDC-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: USDC-based projects, EDC-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.

• If you-re subscribing a user to a double opt-in message type, the user skips the SMS Double Opt-In flow and is immediately subscribed to the message type. To engage a user in the SMS Double Opt-In flow, use the POST /api/subscriptions/subscribeToDoubleOptIn endpoint.

• 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: USDC-based projects, EDC-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.

• If you're subscribing users to a double opt-in message type, the users skip the SMS Double Opt-In flow and are immediately subscribed to the message type. To engage a user in the SMS Double Opt-In flow, use the POST /api/subscriptions/subscribeToDoubleOptIn endpoint.

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

# POST /api/subscriptions/subscribeToDoubleOptIn

Trigger a double opt-in subscription flow
API reference: USDC-based projects, EDC-based projects

This endpoint triggers a SMS Double Opt-In subscription flow for a user. When you call this endpoint, Iterable sends a subscription confirmation message to the user for the specified message type(s).

Once the user responds to the subscription confirmation message, Iterable subscribes them to the message types specified in the request body.

This endpoint can only be used with double opt-in message types for the SMS channel. To learn more about double opt-in message types and how to use this API, read SMS Double Opt-In.

• For messageTypeIds, provide an array of SMS double opt-in message type IDs to which the user should be subscribed.

  If the request body includes a message type that is not a double opt-in message type, the request fails with a 400 status code and an error message provides the failing message type ID.

• For userId or email, provide the user ID or email address of the user to subscribe. Learn about identifying users in API requests.

• For phoneNumber, provide the phone number to set on the specified user's profile. Required for users who don't already have a phone number set.

• For brandName, provide the brand name to use in the double opt-in confirmation message. Optional. Provide to override the brand name set in the message type.

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

Request body:

{
  "messageTypeIds": [
  ],
  "userId": "string",
  "email": "string",
  "phoneNumber": "string",
  "brandName": "string"
}

Sample response:

Request for double opt-in subscription accepted

# Templates

# GET /api/templates

Get project templates
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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>"
 }

# POST /api/templates/email/proof

Send email template proof
API reference: USDC-based projects, EDC-based projects

Send a proof of an email template to a specific user for testing and preview purposes.

Sample request body:

{
  "templateId": 53081,
  "recipientEmail": "test@example.com",
  "dataFields": {
    "firstName": "John",
    "lastName": "Doe"
  }
}

Sample JSON response:

{
  "success": true,
  "messageId": "12345"
}

# POST /api/templates/email/preview

Preview email template with custom data
API reference: USDC-based projects, EDC-based projects

Generate an HTML preview of an email template that renders with custom data. This endpoint simulates how a template would appear when sent to a user, allowing you to test template rendering with specific user, event, and/or data feed data.

Sample request body:

{
  "dataFields": {
    "firstName": "Sarah",
    "lastName": "Johnson",
    "email": "sarah.johnson@example.com",
    "eventName": "purchase",
    "totalValue": 149.99,
    "productName": "Premium Wireless Headphones"
  },
  "dataFeed": {
    "companyName": "Example Corp",
    "supportEmail": "support@example.net"
  },
  "fetchDataFeeds": false
}

Sample response:

<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Welcome Sarah</title> </head> <body style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; background-color: #f5f5f5;"> <div style="background-color: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1);"> <div style="background-color: #4a90e2; color: white; padding: 20px; border-radius: 5px; margin-bottom: 20px;"> <h1 style="margin: 0; font-size: 24px;">Welcome Sarah!</h1> </div> <div style="background-color: #f8f9fa; padding: 15px; border-left: 4px solid #4a90e2; margin: 15px 0;"> <h2 style="margin-top: 0; color: #333;">Your Account</h2> <p style="margin: 5px 0;"><strong>Email:</strong> sarah.johnson@example.com</p> <p style="margin: 5px 0;"><strong>Name:</strong> Sarah Johnson</p> </div> <div style="background-color: #e8f5e8; padding: 15px; border-left: 4px solid #28a745; margin: 15px 0;"> <h2 style="margin-top: 0; color: #333;">Recent Activity</h2> <p style="margin: 5px 0;"><strong>Event:</strong> purchase</p> <p style="margin: 5px 0;"><strong>Amount:</strong> $149.99</p> <p style="margin: 5px 0;"><strong>Product:</strong> Premium Wireless Headphones</p> </div> <div style="margin-top: 20px; padding: 15px; background-color: #f8f9fa; border-radius: 5px;"> <p>Hello Sarah,</p> <p>Thank you for your purchase! We hope you enjoy your Premium Wireless Headphones.</p> <p>Best regards,<br>The Example Corp Team</p> <p style="font-size: 12px; color: #666;">Questions? Contact us at <a href="mailto:support@example.net" style="color: #4a90e2;">support@example.net</a></p> </div> </div> <div><a href="https://www.example.net" rel="noopener" target="_blank">Link</a></div> <div></div> <div><img height="220" src="https://library.iterable.com/0000/00000/09c730f1d8d94c39a015211ab936af88-b7.png" width="220"></div> <div></div> </body> </html>

# GET /api/templates/embedded/get

Get an embedded message template
API reference: USDC-based projects, EDC-based projects

Returns content and metadata for a specific embedded message template.

Sample JSON response:

{
  "templateId": 12345,
  "name": "Welcome Embedded Message",
  "title": "Welcome to Our App!",
  "body": "Thanks for joining us. We're excited to have you on board.",
  "elements": {
    "text": [
      {
        "label": "greeting",
        "text": "Hello {{firstName}}!"
      },
      {
        "label": "description",
        "text": "You've been a member since {{joinDate}}."
      }
    ],
    "buttons": [
      {
        "id": "btn_get_started",
        "title": "Get Started",
        "action": {
          "type": "openUrl",
          "data": "https://example.com/get-started"
        }
      },
      {
        "id": "btn_learn_more",
        "title": "Learn More",
        "action": {
          "type": "openUrl",
          "data": "https://example.com/learn-more"
        }
      }
    ],
    "mediaUrl": "https://example.com/images/welcome-banner.jpg",
    "mediaUrlCaption": "Welcome banner image",
    "defaultAction": {
      "type": "openUrl",
      "data": "https://example.com/default-action"
    }
  },
  "payload": {
    "customData": "value",
    "deepLink": "myapp://welcome"
  },
  "placementId": "home_screen",
  "clientTemplateId": "embedded_welcome_001",
  "messageTypeId": 5001,
  "locale": "en",
  "isDefaultLocale": true,
  "campaignId": 7890,
  "campaignDataFields": {
    "promoCode": "WELCOME2026",
    "discountPercent": 10
  }
}

# POST /api/templates/embedded/upsert

Create an embedded message template
API reference: USDC-based projects, EDC-based projects

Create an embedded message template if it doesn't exist yet, otherwise updates the embedded message template that matches the name provided.

Sample request body:

{
  "clientTemplateId": "embedded_welcome_001",
  "name": "Welcome Embedded Message",
  "title": "Welcome to Our App!",
  "body": "Thanks for joining us. We're excited to have you on board.",
  "elements": {
    "text": [
      {
        "label": "greeting",
        "text": "Hello {{firstName}}!"
      },
      {
        "label": "description",
        "text": "You've been a member since {{joinDate}}."
      }
    ],
    "buttons": [
      {
        "id": "btn_get_started",
        "title": "Get Started",
        "action": {
          "type": "openUrl",
          "data": "https://example.com/get-started"
        }
      },
      {
        "id": "btn_learn_more",
        "title": "Learn More",
        "action": {
          "type": "openUrl",
          "data": "https://example.com/learn-more"
        }
      }
    ],
    "mediaUrl": "https://example.com/images/welcome-banner.jpg",
    "mediaUrlCaption": "Welcome banner image",
    "defaultAction": {
      "type": "openUrl",
      "data": "https://example.com/default-action"
    }
  },
  "payload": {
    "customData": "value",
    "deepLink": "myapp://welcome"
  },
  "placementId": "home_screen",
  "messageTypeId": 5001,
  "locale": "en",
  "isDefaultLocale": true,
  "creatorUserId": "marketing-team@example.com"
}

# POST /api/templates/embedded/update

Update embedded message template
API reference: USDC-based projects, EDC-based projects

Updates a specific embedded message template. Only updates the field(s) included in the request body.

Sample request body:

{
  "templateId": 12345,
  "name": "Welcome Embedded Message Updated",
  "title": "Welcome to Our App - Updated!",
  "body": "Thanks for joining us. We're excited to have you on board. Check out our new features!",
  "elements": {
    "text": [
      {
        "label": "greeting",
        "text": "Hello {{firstName}}! Welcome back."
      },
      {
        "label": "description",
        "text": "You've been a member since {{joinDate}}. Thanks for being part of our community."
      }
    ],
    "buttons": [
      {
        "id": "btn_get_started",
        "title": "Get Started",
        "action": {
          "type": "openUrl",
          "data": "https://example.com/get-started"
        }
      }
    ],
    "mediaUrl": "https://example.com/images/welcome-banner-v2.jpg",
    "mediaUrlCaption": "Welcome banner image",
    "defaultAction": {
        "type": "openUrl",
        "data": "https://example.com/default-action"
      }
  },
  "payload": {
    "customData": "updated_value",
    "deepLink": "myapp://welcome",
    "version": "2.0"
  }
}

# GET /api/templates/push/get

Get a push template
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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: USDC-based projects, EDC-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.

# POST /api/templates/push/proof

Send push template proof
API reference: USDC-based projects, EDC-based projects

Send a proof of a push template to a specific user for testing and preview purposes.

Sample request body:

{
  "templateId": 53081,
  "recipientEmail": "test@example.com",
  "dataFields": {
    "firstName": "John",
    "lastName": "Doe"
  }
}

Sample JSON response:

{
  "success": true,
  "messageId": "12345"
}

# POST /api/templates/sms/upsert

Create an SMS template
API reference: USDC-based projects, EDC-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: USDC-based projects, EDC-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/sms/get

Get an SMS template
API reference: USDC-based projects, EDC-based projects

Returns content and metadata for a specific SMS template.

Sample JSON response:

{
  "templateId": 100692,
  "name": "SMS testing",
  "message": "Here is example message",
  "locale": "en",
  "messageTypeId": 531
}

# POST /api/templates/sms/proof

Send SMS template proof
API reference: USDC-based projects, EDC-based projects

Send a proof of an SMS template to a specific user for testing and preview purposes.

Sample request body:

{
  "templateId": 53081,
  "recipientEmail": "test@example.com",
  "dataFields": {
    "firstName": "John",
    "lastName": "Doe"
  }
}

Sample JSON response:

{
  "success": true,
  "messageId": "12345"
}

# GET /api/templates/inapp/get

Get an in-app template
API reference: USDC-based projects, EDC-based projects

Gets an in-app template, by templateId and locale.

Sample JSON response:

{
  "templateId": 00000000,
  "name": "My In-App template",
  "html": "<!DOCTYPE html>\n<html>\n<head>\n</head>\n<body>\n\n</body>\n</html>",
  "inAppDisplaySettings": {
    "top": {
      "percentage": 0
    },
    "right": {
      "percentage": 0
    },
    "bottom": {
      "percentage": 0
    },
    "left": {
      "percentage": 0
    }
  },
  "webInAppDisplaySettings": {
    "position": "Full"
  },
  "messageTypeId": 000000,
  "isDefaultLocale": true
}