Blueshift Campaigns API

openapi: 3.2.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 Campaigns API
  contact:
    email: support@getblueshift.com
servers:
- url: https://api.getblueshift.com
- url: https://api.eu.getblueshift.com
tags:
- name: Campaigns
  description: Manage your campaigns in Blueshift.
paths:
  /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 archived campaign.
                        name:
                          type: string
                          description: Name of the successfully archived campaign.
                    description: List of campaigns that were successfully archived.
                    example:
                    - uuid: 1a2b3c4d-5678-90ab-cdef-1234567890ab
                      name: Holiday Season Campaign
                    - uuid: 2b3c4d5e-6789-01bc-def0-2345678901cd
                      name: Spring Sale Campaign
                    - uuid: 3c4d5e6f-7890-12cd-ef01-3456789012de
                      name: Summer Offers Campaign
                    - uuid: 4d5e6f7g-8901-23de-f012-4567890123ef
                      name: Autumn Clearance Sale
                    - uuid: 5e6f7g8h-9012-34ef-0123-5678901234fg
                      name: Winter Discounts Campaign
                  failed:
                    type: array
                    items:
                      type: string
                    description: List of UUIDs for campaigns that could not be archived.
                    example: []
        '400':
          description: Bad request - Invalid parameters or request conditions.
        '401':
          description: Unauthorized - Invalid or missing API key.
        '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: Resource not found - One or more campaigns 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_execute:
    post:
      tags:
      - Campaigns
      summary: Bulk trigger campaigns
      description: Use this endpoint to trigger multiple campaigns.
      security:
      - user_api_auth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payloads:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
                    properties:
                      email:
                        description: Specify the email address of the user for whom you want to trigger the campaign.
                        type: string
                        example: john.doe@blueshift.com
                      campaign_uuid:
                        description: Specify the UUID of the campaign that needs to be triggered. 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`.
                        type: string
                        example: 857ad5a5-1cd1-4c8a-bd9b-b2cdbb6595cc
                      email_attachments:
                        type: array
                        description: Specify the URLs of the files that you want to send as an attachment along with the email.
                        example:
                        - '{https://cdn.getblueshift.com/examples/sample.pdf}'
                        - '{https://cdn.getblueshift.com/static/csv/test.csv}'
                        items:
                          type: string
                      _bsft_high_priority:
                        type: boolean
                        description: 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. The default value is false.
                        default: false
                        example: false
                      transaction_uuid:
                        type: string
                        description: 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: a0d1a0f3-6596-4e1c-b487-3639e05b6d2f
            example:
              campaign_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              trigger_at: '2024-03-15T10:30:00Z'
              users:
              - customer_id: user123
                email: user1@acme.com
                transaction_uuid: txn_001
                _bsft_high_priority: true
              - customer_id: user456
                email: user2@acme.com
                transaction_uuid: txn_002
                _bsft_high_priority: false
        description: List of required parameters to trigger a campaign.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    success:
                      type: boolean
        '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_unarchive:
    put:
      summary: Bulk unarchive campaigns
      description: Use this endpoint to unarchive 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 unarchive.
                  example:
                  - uuid1
                  - uuid2
                  - uuid3
                  - uuid4
                  - uuid5
      responses:
        '200':
          description: Campaigns unarchived successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  no_change:
                    type: array
                    items:
                      type: string
                    description: List of UUIDs for campaigns that were already unarchived.
                    example: []
                  blocked:
                    type: array
                    items:
                      type: string
                    description: List of UUIDs for campaigns that could not be unarchived due to restrictions.
                    example: []
                  successful:
                    type: array
                    items:
                      type: object
                      properties:
                        uuid:
                          type: string
                          description: UUID of the successfully unarchived campaign.
                        name:
                          type: string
                          description: Name of the successfully unarchived campaign.
                    description: List of campaigns that were successfully unarchived.
                    example:
                    - uuid: 7e3a2d1e-df8a-4d9c-95f2-a12f4d2f8e19
                      name: Holiday Sale Campaign
                    - uuid: c15f84be-a5d4-4a3c-8096-4c8de82b0df3
                      name: Back-to-School Promotion
                    - uuid: f29d2345-4a6b-432d-a1de-5c3490f74f52
                      name: Summer Discounts Campaign
                    - uuid: 1b5e9876-5c4d-476f-91a8-b43c9ad2e4d1
                      name: Winter Clearance Sale
                    - uuid: e5d2a4f3-d5b4-44a6-803e-8d547c3cdb78
                      name: Black Friday Deals
                  failed:
                    type: array
                    items:
                      type: string
                    description: List of UUIDs for campaigns that could not be unarchived.
                    example: []
        '400':
          description: Bad request - Invalid parameters or request conditions.
        '401':
          description: Unauthorized - Invalid or missing API key.
        '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: Resource not found - One or more campaigns 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/execute:
    post:
      tags:
      - Campaigns
      summary: Trigger a campaign
      description: Use this endpoint to trigger an event-triggered or API-triggered campaign for a specific user.
      security:
      - user_api_auth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              required:
              - email
              - campaign_uuid
              properties:
                email:
                  description: Specify the email address of the user for whom you want to trigger the campaign.
                  type: string
                  example: janedoe@acme.com
                campaign_uuid:
                  description: 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`.
                  type: string
                  example: a43b685d-65e3-5303-64d8-d4b4ab075b5f
                email_attachments:
                  type: array
                  description: Specify the URLs of the files that you want to send as an attachment along with the email.
                  example:
                  - https://cdn.getblueshift.com/examples/sample.pdf
                  - https://cdn.getblueshift.com/static/csv/test.csv
                  items:
                    type: string
                _bsft_high_priority:
                  description: 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. The default value is false.
                  type: boolean
                  default: false
                  example: false
                transaction_uuid:
                  description: 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.
                  type: string
                  example: a0d1a0f3-6596-4e1c-b487-3639e05b6d2f
        description: Required parameters to trigger a campaign.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
          

# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/blueshift/refs/heads/main/openapi/blueshift-campaigns-api-openapi.yml