Iterable Campaigns API
Create, retrieve, and manage marketing campaigns. Access campaign metrics and trigger campaign sends.
Create, retrieve, and manage marketing campaigns. Access campaign metrics and trigger campaign sends.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/iterable-campaigns-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
title: Iterable Campaigns API
version: '1.0'
description: 'Operations tagged campaigns across 2 of this provider''s published API definitions: iterable-api-openapi.json, iterable-rest-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.iterable.com/
- url: https://api.iterable.com/api
description: US Data Center (USDC)
- url: https://api.eu.iterable.com/api
description: European Data Center (EDC)
tags:
- name: campaigns
paths:
/api/campaigns:
get:
description: 'Get metadata about campaigns in a project. Use <code>page</code> and <code>pageSize</code> parameters to paginate results. If the unpaginated campaigns API is allowed for your project, then all campaigns are returned if no pagination parameters are provided. The unpaginated behavior is deprecated and may be removed in the future. <b>Rate limit</b>: 100 requests/second, per project.'
operationId: campaigns
parameters:
- description: Page number (starting at 1).
in: query
name: page
required: false
x-example: 1
schema:
type: integer
format: int32
- description: Number of results to return per page (defaults to 20, maximum of 1000).
in: query
name: pageSize
required: false
x-example: 25
schema:
type: integer
format: int32
- description: 'Field to sort campaigns by, with optional direction prefix. Use - for descending, + or no prefix for ascending. Campaigns can be sorted by id, name, createdAt, updatedAt, or startAt. Examples: -createdAt, +name, id'
in: query
name: sort
required: false
x-example: id
schema:
type: string
default: id
- description: 'Filter campaigns by state. Can be specified multiple times to filter by multiple states. Valid states: Draft, Ready, Scheduled, Running, Finished, Starting, Aborted, Recurring, Archived. Example: ?campaignState=Ready&campaignState=Running'
in: query
name: campaignState
required: false
style: form
explode: true
schema:
type: array
items:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignsResponse'
'401':
description: Invalid API key
summary: List campaign metadata
tags:
- campaigns
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/abort:
post:
description: Abort a campaign given a campaign ID
operationId: abort campaign
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/IterableApiResponse'
'400':
description: Invalid parameters
'401':
description: Invalid API key
summary: Abort a campaign
tags:
- campaigns
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignIdRequest'
description: Abort campaign
required: true
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/activateTriggered:
post:
description: Activate a triggered campaign given a campaign ID
operationId: activate triggered campaign
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/IterableApiResponse'
'400':
description: Invalid parameters
'401':
description: Invalid API key
'403':
description: API triggered campaign activation is not enabled for your project
summary: Activate a triggered campaign
tags:
- campaigns
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignIdRequest'
description: Activate triggered campaign
required: true
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/archive:
post:
description: 'Archives one or more campaigns. This endpoint behaves the same as the archive feature in the UI. Scheduled or recurring campaigns will be cancelled, and running campaigns will be aborted.Archived campaigns will be hidden from the Campaigns page, but can still be viewed in the Archived tab.<b>Rate limit</b>: 5 requests/second, per API key.'
operationId: archive campaigns
responses:
'200':
description: Campaigns archived successfully
'400':
description: Invalid request
'401':
description: Unauthorized
'403':
description: Forbidden
'500':
description: Internal server error
summary: Archive campaigns
tags:
- campaigns
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkArchiveCampaignRequest'
description: Campaign IDs to archive
required: true
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/cancel:
post:
description: Cancel a campaign given a campaign ID
operationId: cancel campaign
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/IterableApiResponse'
'400':
description: Invalid parameters
'401':
description: Invalid API key
summary: Cancel a scheduled or recurring campaign
tags:
- campaigns
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignIdRequest'
description: Cancel campaign
required: true
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/create:
post:
description: 'Creates a new blast or triggered campaign from an existing template. This endpoint can create email, push notification, web push notification, SMS, in-app message, and embedded message campaigns. <strong>Important note</strong>: Global suppression lists are <strong>not</strong> automatically added to campaigns created from this endpoint. To include a global suppression list, include it in the <code>suppressionListIds</code> request parameter. To learn more about creating a campaign with this API, see our <a href="https://support.iterable.com/hc/articles/204780579#post-api-campaigns-create">API Overview</a>.'
operationId: create campaign
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignResponse'
'400':
description: Invalid parameters
'401':
description: Invalid API key
summary: Create a campaign
tags:
- campaigns
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignRequest'
description: Create campaign
required: true
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/deactivateTriggered:
post:
description: Deactivate a triggered campaign given a campaign ID
operationId: Deactivate triggered campaign
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/IterableApiResponse'
'400':
description: Invalid parameters
'401':
description: Invalid API key
'403':
description: API triggered campaign deactivation is not enabled for your project
summary: Deactivate a triggered campaign
tags:
- campaigns
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignIdRequest'
description: Deactivate triggered campaign
required: true
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/metrics:
get:
description: 'Get metrics for a single campaign or multiple campaigns. <b>Rate limit</b>: 10 requests/minute, per project.'
operationId: metrics
parameters:
- description: Campaign(s) to export
in: query
name: campaignId
required: true
style: form
explode: true
schema:
type: array
items:
type: object
- allowEmptyValue: true
description: Export starting from (>=). Accepted formats include YYYY-MM-DD and other ISO 8601 formats.
in: query
name: startDateTime
required: false
schema:
type: string
format: date-time
default: '2018-06-25'
- allowEmptyValue: true
description: Export ending at (<). Accepted formats include YYYY-MM-DD and other ISO 8601 formats.
in: query
name: endDateTime
required: false
schema:
type: string
format: date-time
default: '2018-07-25'
responses:
'200':
description: successful operation
content:
text/plain:
schema:
type: string
'400':
description: Invalid parameters
'401':
description: Invalid API key
summary: Get metrics for campaigns
tags:
- campaigns
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/recurring/{id}/childCampaigns:
get:
description: 'Get child campaigns generated by a recurring campaign. Use <code>page</code> and <code>pageSize</code> parameters to paginate results. If the unpaginated campaigns API is allowed for your project, then all child campaigns are returned if no pagination parameters are provided. The unpaginated behavior is deprecated and may be removed in the future. <b>Rate limit</b>: 100 requests/second, per project.'
operationId: child campaigns
parameters:
- in: path
name: id
required: true
schema:
type: integer
format: int64
- description: Page number (starting at 1).
in: query
name: page
required: false
x-example: 1
schema:
type: integer
format: int32
- description: Number of results to return per page (defaults to 20, maximum of 1000).
in: query
name: pageSize
required: false
x-example: 25
schema:
type: integer
format: int32
- description: 'Field to sort campaigns by, with optional direction prefix. Use - for descending, + or no prefix for ascending. Campaigns can be sorted by id, name, createdAt, updatedAt, or startAt. Examples: -createdAt, +name, id'
in: query
name: sort
required: false
x-example: id
schema:
type: string
default: id
- description: 'Filter campaigns by state. Can be specified multiple times to filter by multiple states. Valid states: Draft, Ready, Scheduled, Running, Finished, Starting, Aborted, Recurring, Archived. Example: ?campaignState=Ready&campaignState=Running'
in: query
name: campaignState
required: false
style: form
explode: true
schema:
type: array
items:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignsResponse'
'400':
description: Invalid parameters
'401':
description: Invalid API key
summary: Get child campaigns of a recurring campaign
tags:
- campaigns
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/trigger:
post:
description: Trigger a campaign given lists
operationId: trigger campaign
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/IterableApiResponse'
'400':
description: Invalid parameters
'401':
description: Invalid API key
'429':
description: Rate limit exceeded
summary: Trigger a campaign
tags:
- campaigns
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerCampaignRequest'
description: Trigger campaign
required: true
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/{campaignId}/schedule:
post:
description: ''
operationId: schedule campaign
parameters:
- in: path
name: campaignId
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/IterableApiResponse'
'400':
description: Invalid parameters
'401':
description: Invalid API key
'403':
description: API scheduling campaigns is not enabled for your project
summary: Schedule existing campaign to be sent
tags:
- campaigns
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleCampaignRequest'
description: Schedule existing campaign request
required: true
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/{campaignId}/send:
post:
description: ''
operationId: send campaign
parameters:
- in: path
name: campaignId
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/IterableApiResponse'
'400':
description: Invalid parameters
'401':
description: Invalid API key
summary: Send existing campaign now
tags:
- campaigns
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/api/campaigns/{id}:
get:
description: 'Get a campaign by ID. <b>Rate limit</b>: 100 requests/second, per project.'
operationId: getCampaign
parameters:
- description: Campaign ID
in: path
name: id
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignDetails'
'400':
description: Invalid parameters
'401':
description: Invalid API key
'404':
description: Campaign not found
summary: Get a campaign
tags:
- campaigns
security:
- api_key: []
servers:
- url: https://api.iterable.com/
/campaigns:
get:
operationId: listCampaigns
summary: List campaigns
description: Retrieves metadata for all campaigns in the project associated with the API key. Returns campaign id, name, type, status, template information, and creation dates.
tags:
- campaigns
responses:
'200':
description: List of campaigns
content:
application/json:
schema:
type: object
properties:
campaigns:
type: array
items:
$ref: '#/components/schemas/Campaign'
'401':
description: Unauthorized
security:
- apiKeyAuth: []
servers:
- url: https://api.iterable.com/api
description: US Data Center (USDC)
- url: https://api.eu.iterable.com/api
description: European Data Center (EDC)
/campaigns/create:
post:
operationId: createCampaign
summary: Create a campaign
description: Creates a new campaign in the Iterable project with the specified name, template, list, and configuration options.
tags:
- campaigns
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignCreateRequest'
responses:
'200':
description: Campaign created successfully
content:
application/json:
schema:
type: object
properties:
msg:
type: string
code:
type: string
params:
type: object
properties:
campaignId:
type: integer
description: The ID of the created campaign
'400':
description: Bad request
'401':
description: Unauthorized
security:
- apiKeyAuth: []
servers:
- url: https://api.iterable.com/api
description: US Data Center (USDC)
- url: https://api.eu.iterable.com/api
description: European Data Center (EDC)
/campaigns/metrics:
get:
operationId: getCampaignMetrics
summary: Get campaign metrics
description: Retrieves engagement metrics for one or more campaigns, including sends, opens, clicks, unsubscribes, bounces, and complaints.
tags:
- campaigns
parameters:
- name: campaignId
in: query
required: true
description: One or more campaign IDs to retrieve metrics for
schema:
type: array
items:
type: integer
- name: startDateTime
in: query
description: Start date for the metrics period in ISO 8601 format
schema:
type: string
format: date-time
- name: endDateTime
in: query
description: End date for the metrics period in ISO 8601 format
schema:
type: string
format: date-time
responses:
'200':
description: Campaign metrics data
content:
application/json:
schema:
type: object
additionalProperties: true
'401':
description: Unauthorized
security:
- apiKeyAuth: []
servers:
- url: https://api.iterable.com/api
description: US Data Center (USDC)
- url: https://api.eu.iterable.com/api
description: European Data Center (EDC)
components:
schemas:
CreateCampaignRequest:
properties:
campaignDataFields:
description: A JSON object containing campaign-level data fields that are available as merge parameters (for example, <code>{{field}}</code>) during message rendering. These fields are available in templates, data feed URLs, and all other contexts where merge parameters are supported. Campaign-level fields are overridden by user and event data fields of the same name.
type: object
dataFields:
description: A JSON object containing data to be statically rendered into the base template at creation time using double square brackets (for example, <code>[[field]]</code>). These values replace the placeholders in the base template and are baked into the campaign template, and cannot be changed later. Supported by email campaigns only.
type: object
defaultTimeZone:
description: For a scheduled blast campaign, when <code>sendMode</code> is <code>RecipientTimeZone</code>, <code>defaultTimeZone</code> specifies the time zone to use when sending to recipients without a known time zone. IANA format (for example, <code>America/Los_Angeles</code>). For more details, see our <a href="https://support.iterable.com/hc/articles/204780579#post-api-campaigns-create">API Overview</a>.
type: string
labelIds:
description: An optional array of label IDs to associate with the new campaign. Labels must exist in the project. Maximum 50 labels allowed.
items:
format: int64
type: integer
type: array
listIds:
description: To create a blast campaign, set <code>listIds</code> to a non-empty array of list IDs to which the campaign should be sent. To create a triggered campaign, omit <code>listIds</code> from the request body.
items:
format: int64
type: integer
type: array
name:
description: The name to use in Iterable for the new campaign.
type: string
scheduleSend:
description: Whether to immediately schedule the blast campaign for sending. Defaults to <code>true</code>. Set to <code>false</code> to create the campaign without scheduling it (the campaign can be scheduled later using <code>POST /api/campaigns/{campaignId}/schedule</code>). Only applies to blast campaigns.
example: false
type: boolean
sendAt:
description: 'A scheduled send time for a new blast campaign, up to 21 days in the future. Format: <code>YYYY-MM-DD HH:MM:SS</code> (UTC). For more details, see our <a href="https://support.iterable.com/hc/articles/204780579#post-api-campaigns-create">API Overview</a>.'
type: string
sendMode:
description: When creating a blast campaign, set <code>sendMode</code> to <code>RecipientTimeZone</code> to have Iterable send the campaign to each recipient at a given local time in their own time zone — the same local time associated with <code>sendAt</code> (UTC) in <code>startTimeZone</code>. Or set <code>sendMode</code> to <code>ProjectTimeZone</code> (default value) to have Iterable send the campaign to all recipients at the UTC time specified by <code>sendAt</code>, regardless of local time zone. For more details, see our <a href="https://support.iterable.com/hc/articles/204780579#post-api-campaigns-create">API Overview</a>.
enum:
- ProjectTimeZone
- RecipientTimeZone
type: string
startTimeZone:
description: For a scheduled blast campaign, when <code>sendMode</code> is <code>RecipientTimeZone</code>, Iterable sends the campaign at the same local time in all recipient time zones — starting with <code>startTimeZone</code>. Recipients in time zones to the east of <code>startTimeZone</code> receive the campaign simultaneously with recipients in <code>startTimeZone</code>, and recipients in time zones to the west of <code>startTimeZone</code> receive the campaign when the same local time arrives in their own time zone. IANA format (for example, <code>America/New_York</code>). For more details, see our <a href="https://support.iterable.com/hc/articles/204780579#post-api-campaigns-create">API Overview</a>.
type: string
suppressionListIds:
description: An array of suppression list IDs to associate with a new blast campaign.
items:
format: int64
type: integer
type: array
templateId:
description: The ID of a template to associate with the new campaign. The new campaign receives a copy of this template.
type: number
required:
- listIds
- name
- templateId
type: object
IterableApiResponse:
properties:
code:
enum:
- Success
- BadApiKey
- BadAuthorizationHeader
- BadJsonBody
- BadParams
- BatchTooLarge
- DatabaseError
- EmailAlreadyExists
- ExternalKeyConflict
- Forbidden
- ForbiddenParamsError
- ForgottenUserError
- GenericError
- InvalidEmailAddressError
- InvalidJwtPayload
- InvalidUserIdError
- JwtUserIdentifiersMismatched
- NotFound
- QueueEmailError
- RateLimitExceeded
- RequestFieldsTypesMismatched
- Unauthorized
- UniqueFieldsLimitExceeded
- UnknownEmailError
- UnknownUserIdError
- UserIdAlreadyExists
type: string
msg:
description: Response description
type: string
params:
description: Additional info
type: object
required:
- code
- msg
type: object
RecipientTimeZoneRequest:
properties:
defaultTimeZone:
description: The fallback time zone if the recipient does not have time zone set in IANA timezone format (e.g. America/New_York, America/Los_Angeles, etc)
type: string
startTimeZone:
description: The starting time zone in IANA timezone format (e.g. America/New_York, America/Los_Angeles, etc)
type: string
required:
- defaultTimeZone
- startTimeZone
type: object
TriggerCampaignRequest:
properties:
allowRepeatMarketingSends:
description: Allow repeat marketing sends? Defaults to true.
type: boolean
campaignId:
format: int64
type: integer
dataFields:
description: Fields to merge into handlebars context
type: object
listIds:
description: A non-empty array of list IDs to send to
items:
format: int64
type: integer
type: array
suppressionListIds:
description: Lists to suppress
items:
format: int64
type: integer
type: array
required:
- campaignId
- listIds
type: object
CampaignsResponse:
properties:
campaigns:
items:
$ref: '#/components/schemas/CampaignDetails'
type: array
nextPageUrl:
description: The URL to the next page of campaigns, if applicable.
type: string
previousPageUrl:
description: The URL to the previous page of campaigns, if applicable.
type: string
totalCampaignsCount:
description: The total count of campaigns across all pages for the supplied query. Only present when using pagination.
type: object
required:
- campaigns
type: object
BulkArchiveCampaignRequest:
properties:
campaignIds:
description: Campaign IDs to archive
items:
type: number
type: array
required:
- campaignIds
type: object
CampaignDetails:
properties:
campaignState:
enum:
- Draft
- Ready
- Scheduled
- Running
- Finished
- Starting
- Aborted
- Recurring
- Archived
type: string
createdAt:
description: Creation timestamp as epoch time in milliseconds
format: int32
type: integer
createdByUserId:
type: string
endedAt:
description: Ended timestamp as epoch time in milliseconds
format: int32
type: integer
id:
type: number
labelIds:
description: Label IDs associated with this campaign.
items:
format: int64
type: integer
type: array
labels:
description: Label names associated with this campaign.
items:
type: string
type: array
listIds:
items:
format: int64
type: integer
type: array
messageMedium:
type: string
name:
type: string
recurringCampaignId:
type: number
sendSize:
type: number
startAt:
description: Start timestamp as epoch time in milliseconds
format: int32
type: integer
suppressionListIds:
items:
format: int64
type: integer
type: array
templateId:
type: number
type:
enum:
- Blast
- Triggered
type: string
updatedAt:
description: Last update timestamp as epoch time in milliseconds
format: int32
type: integer
updatedByUserId:
type: string
workflowId:
type: number
required:
- campaignState
- createdAt
- createdByUserId
- id
- messageMedium
- name
- type
- updatedAt
type: object
ScheduleCampaignRequest:
properties:
recipientTimeZone:
$ref: '#/components/schemas/RecipientTimeZoneRequest'
description: If provided, send campaign based on recipient time zone. If not, default to the project time zone.
sendAt:
description: When to send up to 7 days in the future. ISO-8601 date time format (e.g. 2007-12-03T10:15:30.00Z)
type: string
required:
- sendAt
type: object
CreateCampaignResponse:
properties:
campaignId:
type: number
required:
- campaignId
type: object
CampaignIdRequest:
properties:
campaignId:
type: number
required:
- campaignId
type: object
Campaign:
type: object
description: A marketing campaign in Iterable
properties:
id:
type: integer
description: Campaign ID
name:
type: string
description: Campaign name
type:
type: string
description: Campaign type (blast, triggered, proof, etc.)
templateId:
type: integer
description: Associated template ID
createdAt:
type: string
format: date-time
description: Campaign creation date
updatedAt:
type: string
format: date-time
description: Campaign last update date
messageMedium:
type: string
description: Message medium (Email, Push, SMS, InApp)
enum:
- Email
- Push
- SMS
- InApp
campaignState:
type: string
description: Current state of the campaign
enum:
- Draft
- Scheduled
- Running
- Finished
- Cancelled
listIds:
type: array
description: List IDs the campaign targets
items:
type: integer
labels:
type: array
description: Labels applied to the campaign
items:
type: string
CampaignCreateRequest:
type: object
description: Request body for creating a new campaign
required:
- name
- listIds
- templateId
properties:
name:
type: string
description: Campaign name
listIds:
type: array
description: List IDs to target
items:
type: integer
templateId:
type: integer
description: Template ID to use
suppressionListIds:
type: array
description: List IDs for suppression
items:
type: integer
sendAt:
type: string
format: date-time
description: Scheduled send time in ISO 8601 format
dataFields:
type
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/iterable/refs/heads/main/openapi/iterable-campaigns-api-openapi.yml