openapi: 3.0.0
info:
description: These APIs will help you manage different workflows in Blueshift. Our powerful REST APIs
provide an easy way to integrate your data and third party applications with Blueshift.
version: 1.0.0
title: Blueshift APIs
contact:
email: support@getblueshift.com
servers:
- url: https://api.getblueshift.com
- url: https://api.eu.getblueshift.com
tags:
- name: Adapters
description: Adapters are entities that provide integration to various services with Blueshift. For
example, we provide adapters for various services such as Mailgun, Sendgrid, and Sparkpost for sending
emails, and Infobip and Attentive adapters for SMSes. Similarly, we provide adapters for various channels
and integrations.
- name: Campaigns
description: Manage your campaigns in Blueshift.
- name: Catalog
description: A catalog is a list of items which may include content or products.
- name: Custom user lists
description: A custom user list contains information about the users of your site such as name, email,
phone number, and location. You can use this list as a segment and run campaigns for them.
- name: Customer
description: Blueshift hosts 360 degree customer profile for each of your users to represent all of
their demographic, behavioral and engagement activity.
- name: Customer groups
description: Customer groups link multiple customer profiles to a common parent entity with shared attributes.
Use these endpoints to delete a group or remove a user from a group.
- name: Email template
description: Email template lifecycle management
- name: Email validation
description: Validate single or bulk email addresses to assess deliverability and risk.
- name: Event
description: Use the event APIs to send events from your servers.
- name: External fetch
description: External fetch is a Blueshift capability that lets you include dynamic content from external
servers that is fetched “just in time” before sending a message.
- name: Interest alerts
description: Interest alerts store information about users' interests. When an event occurs in an area
or topic in which multiple users are interested, you can trigger a single API call to send a notification
to all the users who are interested in that topic.
- name: Live Activities
- name: Live content
description: Use the Live content API endpoint to insert content recommendations in your website and
mobile apps.
- name: Promotions
description: Promotions allows you to manage promo codes that you may wish to send to your customers
through Blueshift Campaigns
- name: Push template
description: Push template lifecycle management
- name: SMS template
description: SMS template lifecycle management
- name: Search
description: You can use the `customer_search` API to search for events associated with a customer.
- name: Segments
description: A segment is a list of users that satisfy a criteria. For example, you can create a segment
for users who are located in the San Francisco area and run campaigns for them.
- name: Shared assets
description: Manage reusable assets such as HTML, rich text, subject lines, and visual editor content.
- name: Subscription groups
description: Retrieve subscription groups and view detailed information for each subscription group.
- name: Tags
description: Tags are folder-based entities that you can use to organize your resources. Each tag folder
contains its own isolated set of tags.
paths:
/api/v1/account_adapters:
get:
tags:
- Adapters
summary: List adapters
description: Use this endpoint to list all adapters in your Blueshift account. Adapters connect
your account to third-party services (e.g., Mailgun for email, Infobip for SMS), and you may have
multiple per channel.
security:
- user_api_auth: []
parameters:
- name: channel_name
description: 'Specify the channel type to filter adapters:
• `Email` - Email service providers (e.g., Sendgrid, Mailgun)
• `SMS` - SMS service providers (e.g., Twilio, 46elks)
• `Push Message` - Push notification providers
• `Webhook` - Webhook integrations
• `InApp` - In-app message providers
• `Segment Report` - Segment reporting integrations'
required: true
in: query
schema:
type: string
enum:
- Email
- SMS
- Push Message
- Webhook
- InApp
- Segment Report
example: SMS
- name: adapter_name
description: Filter results by adapter provider name (e.g., `sendgrid`, `sparkpost`, `46elks`,
`twilio`).
in: query
schema:
type: string
example: 46elks
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
description: The unique ID of the adapter.
example: 8147
name:
type: string
description: The provider name of the adapter (e.g., Sendgrid, 46elks).
example: 46elks
primary_name:
type: string
description: The alias name of the adapter that you enter when you create it.
example: test-1
uuid:
type: string
description: The unique UUID of the adapter.
example: aafcf5a4-556f-4334-8cfc-4dfd2a61c691
from_name:
type: string
nullable: true
description: The sender name for the adapter (applicable for Email channel).
example: null
from_address:
type: string
nullable: true
description: The sender email address for the adapter (applicable for Email channel).
example: null
reply_to_address:
type: string
nullable: true
description: The reply-to email address for the adapter (applicable for Email channel).
example: null
created_at:
type: string
format: date-time
description: The date and time when the adapter was created.
example: '2022-04-20T06:29:46.000Z'
updated_at:
type: string
format: date-time
description: The date and time when the adapter was last updated.
example: '2022-04-20T06:29:46.000Z'
is_active:
type: boolean
description: Indicates if the adapter is actively in use.
example: false
cname_record:
type: string
nullable: true
description: The CNAME record pointing to the domain used for sending (applicable
for Email channel).
example: null
bypass_suppression_list:
type: boolean
description: Indicates whether to bypass the suppression list when sending messages.
example: false
channel:
type: string
description: The channel type for this adapter (e.g., Sms, Email, Push).
example: Sms
'400':
description: The request was invalid or cannot be otherwise served. An accompanying error message
will explain further.
'401':
description: Unauthorized - API authentication failed due to an invalid or missing API key.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Not authorized
'403':
description: Forbidden - The API key does not have sufficient permissions to perform this action.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Forbidden
'404':
description: Not Found - No adapters found matching the criteria.
content:
application/json:
schema:
type: array
items: {}
maxItems: 0
example: []
'409':
description: Conflict error, please retry. The request could not be completed due to a conflict
with the current state of the target resource. Re-try with exponential backoff.
'413':
description: You can upload up to 50 users in an API call.
'422':
description: Unprocessable Entity - The request was well-formed but contains semantic errors.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Validation failed
'429':
description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for
recommended throughput.
'500':
description: Internal server error. Contact Blueshift for more information.
'502':
description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff.
'503':
description: Service unavailable, please retry. Service unavailable. Retry with exponential
backoff.
'504':
description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff.
/api/v1/bulkevents:
post:
summary: Send bulk events
description: Use this endpoint to send multiple events from your server or use javascript events
that call the API.
tags:
- Event
security:
- event_api_auth: []
requestBody:
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
type: object
additionalProperties: true
required:
- event
properties:
customer_id:
type: string
description: 'Specify the customer ID. You must atleast specify this value, or
one or more of the following: event/device_id/email.'
example: '48759893'
event:
type: string
description: 'Specify the name of the event. For example, view (product view),
add_to_cart, remove_from_cart, checkout, purchase, search, your_custom_event_name
(custom event) etc. You must atleast specify this value, or one or more of the
following: customer_id/device_id/email.'
example: add_to_cart
device_type:
type: string
description: Specify the type of the device. For example, ios or android.
example: android
device_tokens:
type: string
description: Specify the token of the device.
example: 12d34a5ccf37db694d48d89740bbc1f94da08e25930fc773d2af2aefdd98989c9
device_id:
type: string
description: 'Specify the UUID of the device. You must atleast specify this value,
or one or more of the following: event/customer_id/email.'
example: 8abe3faa-d48d-4e4a-00ca-beae01f1c987
device_idfa:
type: string
description: Sepcify the advertising identifier (idfa) on the device.
example: 39c20522-2ce9-4466-9876-7677b89e4d3b
device_idfv:
type: string
description: Specify the identfier for vendor (idfv) on the device.
example: 6d031ec8-e40c-47d4-9c99-b3e308d8ed78
device_manufacturer:
type: string
description: Specify the manufacturer of the device.
example: apple
os_name:
type: string
description: Specify the OS name.
example: ios
network_carrier:
type: string
description: Specify the carrier on the mobile device.
example: verizon
ip:
type: string
description: Specify the IP address of the device.
example: 192.0.2.1
email:
type: string
description: 'Specify the user''s email address. You must atleast specify this
value, or one or more of the following: event/device_id/customer_id.'
example: janedoe@acme.com
latitude:
type: string
description: Specify the latitude of the user's location.
example: '212.99333'
longitude:
type: string
description: Specify the longitude of the user's location.
example: '-12.39334'
subscription_groups:
type: array
description: Specify the user's subscription preferences.
items:
type: object
properties:
id:
type: string
description: The ID of the subscription group.
subscribed:
type: boolean
description: Enter `true` if the user is subscribed, or `false` if unsubscribed.
example:
- id: newsletter
subscribed: true
- id: weekly_promo
subscribed: false
example:
- customer_id: abc812122
event: identify
device_type: ios
device_tokens: '49244924492449244924492449244924492449244924'
device_id: 8abe3faa-d48d-4e4a-00ca-beae01f1c987
device_idfa: 4d031ed8-c40e-57d4-9c99-a3e308d8cd78
device_idfv: 6d031ec8-e40c-47d4-9c99-b3e308d8ed78
device_manufacturer: apple
os_name: ios
network_carrier: verizon
ip: 201.44.11.21
email: jane.doe@acme.com
latitude: '212.99333'
longitude: '-12.39334'
subscription_groups:
- id: newsletter
subscribed: true
- id: weekly_promo
subscribed: false
- customer_id: '812123'
event: purchase
ip: 201.44.11.22
email: jane.doe@acme.com
revenue: '31.24'
description: Specify device_id. The device_id is the mobile specific (iOS or Android) device identifier
to uniquely identify the mobile device.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: ok or bad request
example: ok
count:
type: integer
description: The count of events sent
example: 0
'400':
description: Bad Request - The request was invalid or cannot be otherwise served. An accompanying
error message will explain further.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
customer_id:
type: string
example: can't be blank
'401':
description: Unauthorized - API authentication failed due to an invalid or missing API key.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Not authorized
'403':
description: Forbidden - The API key does not have sufficient permissions to perform this action.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Forbidden
'404':
description: Not Found - The requested resource was not found.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Not Found
'413':
description: "You can upload maximum 100 products in one api call\t- The server is refusing\
\ to process a request because the request payload is larger than the server is willing or\
\ able to process."
'422':
description: Unprocessable Entity - Some/all of the products have invalid data, please check
the response for more information on.
'429':
description: Rate limit exceeded - Too many requests
'500':
description: "Internal Server Error\t- Please contact blueshift for more information"
'502':
description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff
'503':
description: Service unavailable, please retry - Service Unavailable, re-try with exponential
backoff
'504':
description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential
backoff
/api/v1/campaigns.json:
get:
tags:
- Campaigns
summary: Performance summary
description: Use this endpoint to export the performance data of all the campaigns for a given date
range.
security:
- user_api_auth: []
parameters:
- name: start_time
description: Specify a timestamp in the ISO 8601 format to filter the performance data of the
campaigns that ran after it.
example: '2023-05-05T20:41:21.000Z'
in: query
required: true
schema:
type: string
format: date-time
- in: query
name: end_time
description: Specify a timestamp in the ISO 8601 format to filter the performance data of the
campaigns that ran before it.
example: '2023-10-06T20:41:21.000Z'
required: true
schema:
type: string
format: date-time
- name: status
description: Specify a status to filter the campaigns.
example: launched
in: query
schema:
type: string
enum:
- launched
- draft
- paused
- completed
- name: tag_data
description: Specify tags to filter the campaigns.
example: Regions:NA,EU,APAC,LATAM,GreaterChina
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
campaigns:
type: array
items:
type: object
properties:
campaign_executing:
type: boolean
example: false
campaign_execution_ended_at:
type: string
format: date-time
example: '2024-10-03T04:57:24.000Z'
campaign_execution_started_at:
type: string
format: date-time
example: '2023-10-05T04:57:24.000Z'
created_at:
type: string
format: date-time
example: '2023-10-03T04:57:24.000Z'
currency:
type: string
example: USD
enddate:
type: string
format: date
example: '2024-05-03T04:57:24.000Z'
exec_term:
type: string
enum:
- on_going
example: on_going
name:
type: string
example: Daily market tips
recurring_number:
type: number
example: '1'
recurring_schedule:
type: string
example: continuously
recurring_time:
type: number
description: Schedule a recurring campaign to execute sends at a specific time
of a day. The system tracks the campaign's last execution time (`last_recurring_execution_started_at`)
and uses it to determine the next scheduled run.
example: '2024-01-03T14:45:00.000Z'
recurring_unit:
type: string
example: day
segment_name:
type: string
example: Daily market tips segment
description: The segment for which the campaign is running
segment_uuid:
type: string
example: 9dfd5cdc-fedc-40b5-8c65-ba533c57c8bf
startdate:
type: string
format: date-time
example: '2024-01-02T14:45:00.000Z'
statistics:
type: object
properties:
activations:
type: number
add_to_carts:
type: number
assigns:
type: number
attributions:
type: object
bounces:
type: number
checkouts:
type: number
clicks:
type: number
deliveries:
type: number
end_time:
type: string
format: date-time
media_spent:
type: number
opens:
type: number
example: 20
pageloads:
type: number
example: 5
purchases:
type: number
example: 75
revenue:
type: number
example: 19618
sends:
type: number
example: 110
spam_reports:
type: number
example: 2
start_time:
type: string
format: date-time
timezone:
type: string
example: Pacific/Los_Angeles
unique_clicks:
type: number
example: 150
unique_opens:
type: number
example: 250
unsubscribes:
type: number
example: 2
visits:
type: number
example: 2160
status:
type: string
enum:
- launched
- draft
- paused
example: paused
updated_at:
type: string
format: date-time
example: '2024-05-05T20:41:21.000Z'
uuid:
type: string
'400':
description: 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.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Bad Request
'401':
description: Unauthorized - API authentication failed due to an invalid or missing API key.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Not authorized
'403':
description: Forbidden - The API key does not have sufficient permissions to perform this action.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Forbidden
'404':
description: Not Found - The requested resource was not found.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Not Found
'422':
description: Unprocessable Entity - The request was well-formed but contains semantic errors.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Validation failed
'429':
description: Too Many Requests - The request limit has been exceeded. Reduce request frequency.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too Many Requests
'500':
description: Internal Server Error - An unexpected server error occurred. Contact support if
the issue persists.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Internal Server Error
'502':
description: Bad Gateway - The server received an invalid response. Retry the request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Bad Gateway
'503':
description: Service Unavailable - The service is temporarily unavailable. Try again later.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Service Unavailable
'504':
description: Gateway Timeout - The server took too long to respond. Retry the request with exponential
backoff.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Gateway Timeout
/api/v1/campaigns/bulk_archive:
put:
summary: Bulk archive campaigns
description: Use this endpoint to archive multiple campaigns by providing an array of UUIDs.
tags:
- Campaigns
security:
- user_api_auth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
uuid:
type: array
items:
type: string
description: List of campaign UUIDs to archive.
example:
- uuid1
- uuid2
- uuid3
- uuid4
- uuid5
responses:
'200':
description: Campaigns archived successfully.
content:
application/json:
schema:
type: object
properties:
no_change:
type: array
items:
type: string
description: List of UUIDs for campaigns that were already archived.
example: []
blocked:
type: array
items:
type: string
description: List of UUIDs for campaigns that could not be archived due to restrictions.
example: []
successful:
type: array
items:
type: object
properties:
uuid:
type: string
description: UUID of the successfully archi
# --- truncated at 32 KB (552 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/blueshift/refs/heads/main/openapi/blueshift-openapi.yml