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

Click for instructions

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.

Note for developers

When making API requests programmatically, authentication requires a Base64-encoded API key. You can generate this using a trusted Base64 encoder.

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. Applies only to event-triggered campaigns.
`segment_uuid`	`string`	✅ Yes	UUID of the segment associated with this campaign. Required for one-time campaigns.
`triggering_event_name`	`string`	❌ No	The event that triggers this campaign. Default: `API triggered`.
`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.
`skip_incrementing_user` `_message_limits`	`boolean`	❌ No	Determines if campaign messages count towards a 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.
`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: `once_at_any_time`.
`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: `blueshift`.
`utm_campaign`	`string`	❌ No	UTM Campaign name. Default: campaign name.
`utm_medium`	`string`	❌ No	UTM Medium (e.g., `email`, `push`). Default: inferred from the template.
`utm_content`	`string`	❌ No	UTM Content.
`utm_term`	`string`	❌ No	UTM Term for keyword tracking.
`account_adapter_uuid`	`string`	❌ No	UUID of the adapter for message sending.
`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 UTM parameters.

Example requests & responses

Event-triggered campaign

{
  "send_to_unsubscribed": false,
  "journey_concurrency": "once_at_any_time",
  "name": "Spring Sale 2025",
  "author": "john.doe@example.com",
  "launch": true,
  "startdate": "2025-03-01T09:00:00Z",
  "enddate": "2025-03-15T23:59:59Z",
  "segment_uuid": "9a87f6e3-5c21-4c8d-9b2a-763cd01234ab",
  "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": "team@example.com",
  "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": "promo@example.com",
      "reply_to_address": "support@example.com",
      "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": "alex.smith@example.com",
  "launch": true,
  "startdate": "2025-11-20T08:00:00Z",
  "enddate": "2025-11-30T23:59:59Z",
  "segment_uuid": "5d4a3c2b-6e7f-48c9-a1b2-89cd345678ef",
  "triggering_event_name": "holiday_promo",
  "bypass_message_limits": false,
  "bypass_global_inclusion_segment": false,
  "skip_incrementing_user_message_limits": false,
  "remove_unsubscribe_from_email_headers": false,
  "send_summary_emails": "marketing@example.com",
  "send_to_unsubscribed": false,
  "journey_concurrency": "once_per_lifetime",
  "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": "deals@example.com",
      "reply_to_address": "help@example.com",
      "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",
    "enddate": "2025-11-30T23:59:59.000Z",
    "status": "launched",
    "segment_uuid": "1a2b3c4d-5678-90ef-ghij-123456789abc",
    "send_summary_emails": "marketing@example.com",
    "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": "jane.doe@example.com",
  "launch": true,
  "startdate": "2025-03-10T08:30:00Z",
  "enddate": "2025-03-31T23:59:59Z",
  "segment_uuid": "4f5e6d7c-8a9b-0d1e-2f3g-456789abcdef",
  "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": "loyalty@example.com",
  "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": "vip@example.com",
      "reply_to_address": "concierge@example.com",
      "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

Status code	Description	Example response
400 Bad Request	The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, request formatting issues, and conflicts such as duplicate campaign names.	`{ "errors": { "name": ["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 requested API endpoint does not exist. Verify the request path.	`{ "message": "Endpoint not found" }`
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 while processing the request. 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. Implement exponential backoff and retry.	`{ "message": "Gateway Timeout - The server took too long to respond. Retry with exponential backoff." }`