API at a glance

Description: Use this endpoint to trigger an event-triggered or API-triggered campaign for a specific user. This API allows you to programmatically send transactional or event-based campaigns.

🚧
Note
The endpoint works for campaigns that are set to trigger using an API call. In an event triggered campaign, in the Journey Start trigger, set When event occurs to API Endpoint is called.

Try it out

Add the User API key as the Username and leave the Password field blank.
Click the Base URL dropdown and select the API endpoint URL for your Blueshift region.
Click Try It.

You can also try the API using Blueshift's API collection in Postman.

Things to know before you start

This endpoint works only with campaigns configured as event-triggered or API-triggered.
The campaign must have triggering_event_name left blank (for API-triggered) or match the event you're sending.
Required identifier: You must provide a valid user identifier (email, customer_id, or other configured identifier).
Email attachments: Attachment URLs must be publicly accessible.
Transaction UUID: Use this to prevent duplicate messages. Blueshift returns 200 OK for duplicate requests with the same transaction_uuid.
Use case: Best for sending transactional emails (order confirmations, password resets) or triggering event-based campaigns via API.

👍
Finding the campaign UUID
The campaign UUID is visible in the browser's address bar when you open a campaign. For example: https://app.getblueshift.com/dashboard#/app/campaigns/<CAMPAIGN_UUID>/edit_v3/journey

Request parameters

Check out the request parameters

Request body parameters

Parameter	Type	Required	Description
`email`	`string`	✅ Yes	Specify the email address of the user for whom you want to trigger the campaign.
`campaign_uuid`	`string`	✅ Yes	Specify the UUID of the campaign that you want to trigger. You can copy the UUID from the URL of the campaign on the Blueshift app. For example, if you open a campaign in the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/campaigns/<CAMPAIGN_UUID>/details`.
`email_attachments`	`array`	❌ No	Specify the URLs of the files that you want to send as an attachment along with the email. URLs must be publicly accessible.
`_bsft_high_priority`	`boolean`	❌ No	Set to true if the campaign must be processed as a high priority campaign. Blueshift first processes all high priority campaigns in a first in first out order. This is followed by all other campaigns in a first in first out order. * Default: `false`.
`transaction_uuid`	`string`	❌ No	Optionally include the transaction UUID (must be a well formed UUID) to avoid duplicate messages. The API returns a 200 status code for a duplicate request along with a message noting that a request with the given transaction UUID was already processed.

Example requests & responses

Basic campaign trigger

{
  "email": "janedoe@acme.com",
  "campaign_uuid": "a43b685d-65e3-5303-64d8-d4b4ab075b5f"
}

{
  "success": true
}

Campaign trigger with attachments

{
  "email": "janedoe@acme.com",
  "campaign_uuid": "a43b685d-65e3-5303-64d8-d4b4ab075b5f",
  "email_attachments": [
    "https://cdn.getblueshift.com/examples/sample.pdf",
    "https://cdn.getblueshift.com/static/csv/test.csv"
  ],
  "_bsft_high_priority": false,
  "transaction_uuid": "a0d1a0f3-6596-4e1c-b487-3639e05b6d2f"
}

{
  "success": true
}

High priority campaign trigger

{
  "email": "vip@acme.com",
  "campaign_uuid": "a43b685d-65e3-5303-64d8-d4b4ab075b5f",
  "_bsft_high_priority": true,
  "transaction_uuid": "b1e2f4g5-7890-5e2f-c598-4740f96e7c3a"
}

{
  "success": true
}

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, formatting issues, or conflicts such as duplicate data.	`{ "success": false, "error": "Invalid request parameters" }`
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": "Forbidden" }`
404 Not Found	The specified campaign was not found. Verify the campaign UUID.	`{ "message": "Not Found" }`
422 Unprocessable Entity	Request validation failed. Common reasons include: campaign is not event/API triggered (error_code: 101), campaign cannot be triggered through this endpoint (error_code: 102), or a valid user identifier is missing (error_code: 102).	`{ "success": false, "error": "campaign is not event/API triggered", "error_code": 101 }`
429 Too Many Requests	The request limit has been exceeded. Reduce request frequency.	`{ "message": "Too Many Requests" }`
500 Internal Server Error	An unexpected server error occurred. Contact support if the issue persists.	`{ "message": "Internal Server Error" }`
502 Bad Gateway	The server received an invalid response. Retry the request.	`{ "message": "Bad Gateway" }`
503 Service Unavailable	The service is temporarily unavailable. Try again later.	`{ "message": "Service Unavailable" }`
504 Gateway Timeout	The server took too long to respond. Retry the request with exponential backoff.	`{ "message": "Gateway Timeout" }`