Create a campaign

API at a glance

Description: This API allows you to create and launch marketing campaigns programmatically.

Supported campaign types:

event_triggered
one_time

Authentication & testing

Testing the API on this page

How to try it here

Use your User API Key as the Username (leave Password blank).

Select the appropriate API endpoint based on your Blueshift region.

Enter the necessary parameters and click Try It to run the request.

Authentication using Base64 encoding

Note for developers

API requests require authentication using HTTP Basic Authentication with an API key. The API key serves as the username, while the password field should be left empty. The format to encode is: your_api_key: (note the trailing colon).

This string must be Base64-encoded and included in the request's Authorization header as follows:

Authorization: Basic encoded_value

You can generate the encoded value using a trusted Base64 encoder.

Postman collection

Try it with Postman: Explore the API using Blueshift's Postman collection.

Things to know before you start

enddate, triggering_event_name, and journey_concurrency apply only to event-triggered campaigns.
segment_uuid and send_summary_emails apply only to one-time campaigns.
Only one trigger can be included in this API request. Multiple triggers will result in an error.
Campaigns cannot be modified using this API after creation (e.g., adding triggers).
Filters or delays cannot be applied to campaign triggers via this API.
Retrieve seed list UUIDs: Please get the seed list UUIDs using the Seed Lists API.
Use case: Best for programmatically launching marketing campaigns like daily newsletters.

Request parameters

Check out the request parameters

Campaign parameters

Note: Unless otherwise specified in the description, all parameters apply to both event-triggered and one-time campaigns.

Parameter	Type	Required	Description
`campaign_type`	`string`	✅ Yes	Specifies how the campaign is triggered. Options:* `event_triggered`, `one_time`.
`name`	`string`	✅ Yes	The name of the campaign.
`author`	`string`	❌ No	Email address of the campaign author.
`launch`	`boolean`	❌ No	Determines if the campaign should be launched immediately (`true`) or saved as a draft (`false`). Default:* `true`.
`startdate`	`string (ISO 8601)`	✅ Yes	Campaign start time in ISO 8601 format. Default: current time.
`enddate`	`string (ISO 8601)`	❌ No	Campaign end time in ISO 8601 format. Default: runs indefinitely. Applicable only for event-triggered campaigns.
`segment_uuid`	`string`	✅ Yes	UUID of the segment associated with this campaign. Required only for one-time campaigns.
`triggering_event_name`	`string`	❌ No	The event that triggers this campaign. Must match an Event Attribute in the Events dashboard. If left blank, the campaign is API triggered and can only be triggered via the Campaign Execute API. Applicable only for event-triggered campaigns.
`bypass_message_limits`	`boolean`	❌ No	Whether to bypass messaging limits. Default:* `false`.
`bypass_global_inclusion` `_segment`	`boolean`	❌ No	Whether to send messages to users outside the global inclusion segment. Default:* `false`.
`skip_incrementing_user` `_message_limits`	`boolean`	❌ No	Controls whether sent messages are excluded from the user’s message counts.* When set to `true`, messages do not count towards the user’s message limits. Default:* `false`.
`remove_unsubscribe_from` `_email_headers`	`boolean`	❌ No	Whether to exclude unsubscribe headers from emails. Default:* `false`.
`send_summary_emails`	`string`	❌ No	Email address to receive the campaign execution summary. Applicable only for one-time campaigns.
`send_to_unsubscribed`	`boolean`	❌ No	Whether to send messages to unsubscribed users. Default:* `false`.
`journey_concurrency`	`string`	❌ No	Defines how often a user can enter the journey. Options: `once_per_lifetime`, `once_at_any_time`, `multiple`. Default:* `multiple`. Applicable only for event-triggered campaigns.
`seed_list_uuids`	`array`	❌ No	An array of seed list UUIDs for testing campaigns.
`tag_data`	`string`	❌ No	Tags associated with the campaign (e.g., `Regions:USA,Canada`).

Triggers

Note: Triggers are required for both event-triggered and one-time campaign types. The API supports only one trigger per campaign.

Parameter	Type	Required	Description
`trigger_name`	`string`	✅ Yes	Name of the trigger for reference.
`template_uuid`	`string`	✅ Yes	UUID of the template linked to this trigger (email, push, SMS, etc.).
`utm_source`	`string`	❌ No	UTM Source for tracking. Default:* Set based on the account's backend configuration.
`utm_campaign`	`string`	❌ No	UTM Campaign name. Default:* Set based on the account's backend configuration.
`utm_medium`	`string`	❌ No	UTM Medium (e.g., `email`, `push`). Default:* Set based on the account's backend configuration.
`utm_content`	`string`	❌ No	Identifies specific content variations within the campaign. Default:* Set based on the account's backend configuration.
`utm_term`	`string`	❌ No	UTM Term for keyword tracking. Default:* Set based on the account's backend configuration.
`account_adapter_uuid`	`string`	❌ No	UUID of the adapter for message sending. If left blank, the trigger uses the default adapter for the channel. It does not apply to cloud app triggers. Leave blank if using: `account_adapter` `_liquid_expression`.
`account_adapter` `_liquid_expression`	`string`	❌ No	Liquid expression to dynamically assign an adapter UUID. Leave `account_adapter_uuid` blank when using this.
`from_name`	`string`	❌ No	Sender's name for email campaigns.
`from_address`	`string`	❌ No	Sender's email address. It must match the adapter domain.
`reply_to_address`	`string`	❌ No	Email address where replies are sent.
`custom_url_params`	`array`	❌ No	Custom tracking parameters added to links.

Example requests & responses

Event-triggered campaign

{
  "send_to_unsubscribed": false,
  "journey_concurrency": "once_at_any_time",
  "name": "Spring Sale 2025",
  "author": "[email protected]",
  "launch": true,
  "startdate": "2025-03-01T09:00:00Z",
  "enddate": "2025-03-15T23:59:59Z",
  "triggering_event_name": "cart_abandonment",
  "bypass_message_limits": false,
  "bypass_global_inclusion_segment": false,
  "skip_incrementing_user_message_limits": false,
  "remove_unsubscribe_from_email_headers": false,
  "send_summary_emails": "[email protected]",
  "seed_list_uuids": [
    "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  ],
  "triggers": [
    {
      "trigger_name": "cart_reminder",
      "template_uuid": "d3f2c1b5-6789-4a0b-85c3-2d4e56789abc",
      "utm_source": "campaigns",
      "utm_campaign": "spring_sale_2025",
      "utm_medium": "email",
      "utm_content": "limited_time_discount",
      "utm_term": "exclusive_deal",
      "from_name": "Retail Store",
      "from_address": "[email protected]",
      "reply_to_address": "[email protected]",
      "custom_url_params": [
        { "name": "category", "value": "electronics" },
        { "name": "offer", "value": "20_percent_off" }
      ],
      "account_adapter_uuid": "e4d5c6f7-89ab-4cde-90fa-bc12345678de"
    }
  ],
  "tag_data": "Region:US,EU,APAC"
}

{
  "campaign": {
    "uuid": "21a5b6c7-8901-4d2e-9f3g-45678abcdef",
    "name": "Spring Sale 2025",
    "startdate": "2025-03-01T09:00:00.000Z",
    "enddate": "2025-03-15T23:59:59.000Z",
    "status": "launched",
    "triggering_event_name": "cart_abandonment",
    "journey_concurrency": "once_at_any_time",
    "author": "John Doe",
    "tag_data": "Region:US,EU,APAC"
  }
}

One-time campaign

{
  "name": "Holiday Deals 2025 - One Time",
  "author": "[email protected]",
  "launch": true,
  "startdate": "2025-11-20T08:00:00Z",
  "segment_uuid": "5d4a3c2b-6e7f-48c9-a1b2-89cd345678ef",
  "bypass_message_limits": false,
  "bypass_global_inclusion_segment": false,
  "skip_incrementing_user_message_limits": false,
  "remove_unsubscribe_from_email_headers": false,
  "send_summary_emails": "[email protected]",
  "send_to_unsubscribed": false,
  "seed_list_uuids": [
    "1a2b3c4d-5678-90ef-ghij-123456789abc"
  ],
  "tag_data": "Region:North America,Europe|Category:Fashion,Accessories",
  "triggers": [
    {
      "trigger_name": "holiday_discount_alert",
      "template_uuid": "9f8e7d6c-5b4a-3210-cdef-87654321abcd",
      "utm_source": "seasonal_campaigns",
      "utm_campaign": "holiday_deals_2025",
      "utm_medium": "email",
      "utm_content": "exclusive_holiday_discounts",
      "utm_term": "early_access",
      "from_name": "Your Favorite Store",
      "from_address": "[email protected]",
      "reply_to_address": "[email protected]",
      "custom_url_params": [
        { "name": "promo", "value": "black_friday" },
        { "name": "discount", "value": "30_percent_off" }
      ],
      "account_adapter_uuid": "abcd1234-ef56-78gh-90ij-klmnopqrstuv"
    }
  ]
}

{
  "campaign": {
    "uuid": "5a4b3c2d-6e7f-48c9-a1b2-89cd345678ef",
    "name": "Holiday Deals 2025 - One Time",
    "startdate": "2025-11-20T08:00:00.000Z",
    "status": "launched",
    "segment_uuid": "1a2b3c4d-5678-90ef-ghij-123456789abc",
    "send_summary_emails": "[email protected]",
    "author": "Alex Smith",
    "tag_data": "Region:North America,Europe|Category:Fashion,Accessories"
  }
}

Request - using adapter Liquid expression

{
  "send_to_unsubscribed": false,
  "journey_concurrency": "multiple",
  "name": "VIP Customer Offer - Q1 2025",
  "author": "[email protected]",
  "launch": true,
  "startdate": "2025-03-10T08:30:00Z",
  "enddate": "2025-03-31T23:59:59Z",
  "triggering_event_name": "loyalty_bonus",
  "bypass_message_limits": true,
  "bypass_global_inclusion_segment": false,
  "skip_incrementing_user_message_limits": false,
  "remove_unsubscribe_from_email_headers": true,
  "send_summary_emails": "[email protected]",
  "triggers": [
    {
      "trigger_name": "loyalty_reward",
      "template_uuid": "a1b2c3d4-5678-90fe-dcba-654321fedcba",
      "utm_source": "vip_rewards",
      "utm_campaign": "q1_bonus_2025",
      "utm_medium": "email",
      "utm_content": "vip_promo_code",
      "utm_term": "exclusive_vip",
      "from_name": "Retail Store VIP Rewards",
      "from_address": "[email protected]",
      "reply_to_address": "[email protected]",
      "custom_url_params": [
        { "name": "membership_level", "value": "gold" },
        { "name": "bonus_points", "value": "5000" }
      ],
      "account_adapter_liquid_expression": "{% if user.extended_attributes.loyalty_tier == 'gold' %} 'vip-adapter-uuid' {% else %} 'default-adapter-uuid' {% endif %}"
    }
  ],
  "tag_data": "Region:NorthAmerica,Europe"
}

API error responses

Note
The following error codes are commonly returned by Blueshift APIs. Depending on the specific endpoint, not all may apply.

Status code	Description	Example responses
400 Bad Request	The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data.	`{ "errors": { "name": ["can't be blank"] } }` `{ "errors": { "startdate": ["can't be blank"] } }`
401 Unauthorized	API authentication failed due to an invalid or missing API key.	`{ "message": "Not authorized" }`
403 Forbidden	The API key does not have sufficient permissions to perform this action.	`{ "message": "Permission denied" }`
404 Not Found	The specified campaign was not found. Verify the campaign UUID.	`{ "message": "Campaign not found" }`
422 Unprocessable Entity	The campaign cannot be paused due to its current status (e.g., already completed or archived). One or more scheduling parameters may be invalid (if applicable).	`{ "message": "Campaign cannot be paused in its current status." }` `{ "message": "Invalid schedule values" }`
429 Too Many Requests	The request limit has been exceeded. Reduce request frequency.	`{ "message": "Rate limit exceeded" }`
500 Internal Server Error	An unexpected server error occurred. Contact support if the issue persists.	`{ "message": "Internal Server Error - Please contact support for more information." }`
502 Bad Gateway	The server received an invalid response. Retry the request.	`{ "message": "Bad Gateway - Please retry the request." }`
503 Service Unavailable	The service is temporarily unavailable. Try again later.	`{ "message": "Service Unavailable - The service is temporarily unavailable. Try again later." }`
504 Gateway Timeout	The server took too long to respond. Retry the request with exponential backoff.	`{ "message": "Gateway Timeout - The server took too long to respond. Retry with exponential backoff." }`