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).
- 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
, andjourney_concurrency
apply only to event-triggered campaigns.segment_uuid
andsend_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. Default: API triggered 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. |
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. 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: once_at_any_time .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: 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": "[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 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." } |