ITiterable
campaigns

Create a campaign

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

post/api/campaigns/create

Request

  • Base URL
    https://api.iterable.com
  • Auth
    API key in header Api-Key

Request body

campaignDataFieldsobject

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.

dataFieldsobject

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.

defaultTimeZonestring

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

labelIdsinteger[]

An optional array of label IDs to associate with the new campaign. Labels must exist in the project. Maximum 50 labels allowed.

listIdsinteger[] required

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.

namestring required

The name to use in Iterable for the new campaign.

scheduleSendboolean

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.

sendAtstring

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

sendMode'ProjectTimeZone' | 'RecipientTimeZone'

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

shortenLinksboolean

Whether links in the campaign template should be shortened. Returns HTTP 400 if true when link shortening is not enabled for the project. Omitted or false is ignored.

startTimeZonestring

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

suppressionListIdsinteger[]

An array of suppression list IDs to associate with a new blast campaign.

templateIdnumber required

The ID of a template to associate with the new campaign. The new campaign receives a copy of this template.

Response

successful operation

campaignIdnumber required

Changes

No recorded changes to this operation across all 4 revisions of this API.