Create a campaign

Use this endpoint to create a campaign and specify its attributes.

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).
  • User API Key Location
  • Select the appropriate API endpoint based on your Blueshift region.
  • API - Select 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.

ParameterTypeRequiredDescription
campaign_typestring✅ YesSpecifies how the campaign is triggered. Options: event_triggered, one_time.
namestring✅ YesThe name of the campaign.
authorstring❌ NoEmail address of the campaign author.
launchboolean❌ NoDetermines if the campaign should be launched immediately (true) or saved as a draft (false). Default: true.
startdatestring (ISO 8601)✅ YesCampaign start time in ISO 8601 format. Default: current time.
enddatestring (ISO 8601)❌ NoCampaign end time in ISO 8601 format. Default: runs indefinitely.

Applicable only for event-triggered campaigns.
segment_uuidstring✅ YesUUID of the segment associated with this campaign.

Required only for one-time campaigns.
triggering_event_namestring❌ NoThe event that triggers this campaign. Default: API triggered

Applicable only for event-triggered campaigns.
bypass_message_limitsboolean❌ NoWhether to bypass messaging limits. Default: false.
bypass_global_inclusion
_segment
boolean❌ NoWhether to send messages to users outside the global inclusion segment.
skip_incrementing_user
_message_limits
boolean❌ NoDetermines if campaign messages count towards a user’s message limits. Default: false.
remove_unsubscribe_from
_email_headers
boolean❌ NoWhether to exclude unsubscribe headers from emails. Default: false.
send_summary_emailsstring❌ NoEmail address to receive the campaign execution summary.

Applicable only for one-time campaigns.
send_to_unsubscribedboolean❌ NoWhether to send messages to unsubscribed users. Default: false.
journey_concurrencystring❌ NoDefines how often a user can enter the journey. Options: once_per_lifetime, once_at_any_time, multiple. Default: once_at_any_time.

Applicable only for event-triggered campaigns.
seed_list_uuidsarray❌ NoAn array of seed list UUIDs for testing campaigns.
tag_datastring❌ NoTags 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.

ParameterTypeRequiredDescription
trigger_namestring✅ YesName of the trigger for reference.
template_uuidstring✅ YesUUID of the template linked to this trigger (email, push, SMS, etc.).
utm_sourcestring❌ NoUTM Source for tracking. Default: blueshift.
utm_campaignstring❌ NoUTM Campaign name. Default: campaign name.
utm_mediumstring❌ NoUTM Medium (e.g., email, push). Default: inferred from the template.
utm_contentstring❌ NoUTM Content.
utm_termstring❌ NoUTM Term for keyword tracking.
account_adapter_uuidstring❌ NoUUID of the adapter for message sending.
account_adapter_liquid
_expression
string❌ NoLiquid expression to dynamically assign an adapter UUID. Leave account_adapter_uuid blank when using this.
from_namestring❌ NoSender's name for email campaigns.
from_addressstring❌ NoSender's email address. It must match the adapter domain.
reply_to_addressstring❌ NoEmail address where replies are sent.
custom_url_paramsarray❌ NoCustom UTM parameters.

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
Status codeDescriptionExample response
400 Bad RequestThe 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 UnauthorizedAPI authentication failed due to an invalid or missing API key.{ "message": "Not authorized" }
403 ForbiddenThe API key does not have sufficient permissions to perform this action.{ "message": "Permission denied" }
404 Not FoundThe requested API endpoint does not exist. Verify the request path.{ "message": "Endpoint not found" }
429 Too Many RequestsThe request limit has been exceeded. Reduce request frequency.{ "message": "Rate limit exceeded" }
500 Internal Server ErrorAn unexpected server error occurred. Contact support if the issue persists.{ "message": "Internal Server Error - Please contact support for more information." }
502 Bad GatewayThe server received an invalid response while processing the request. Retry the request.{ "message": "Bad Gateway - Please retry the request." }
503 Service UnavailableThe service is temporarily unavailable. Try again later.{ "message": "Service Unavailable - The service is temporarily unavailable. Try again later." }
504 Gateway TimeoutThe 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." }
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!