openapi: 3.0.3
info:
  title: Bluecore Authn Transactional API
  version: 0.0.1
  description: The Bluecore API supports the REST architecture style and uses JSON requests and responses. It exposes Bluecore's Customer (Shopper) profiles, Eligibility (subscription/consent) management, and Communicate (Direct Send + Transactional messaging) surfaces, plus OAuth 2.0 client-credentials authentication. Harvested by API Evangelist from the per-operation OpenAPI definitions published at developers.bluecore.com.
  contact:
    name: Bluecore Support
    email: support@bluecore.com
    url: https://developers.bluecore.com/
servers:
- url: https://a.bluecore.com/api
  description: Bluecore API server
tags:
- name: Transactional
paths:
  /namespaces/{namespace}/transactional-messages/{id}:
    get:
      tags:
      - Transactional
      summary: Retrieve transactional message status
      operationId: Transactional_Get
      parameters:
      - name: namespace
        in: path
        description: The unique name of the Bluecore environment.
        required: true
        schema:
          type: string
        example: bluestore
      - name: id
        in: path
        description: 'The idempotency key used when sending the transactional message.  Used to retrieve the message information and status history. Allowed characters:  alphanumeric, colon (:), underscore (_), period (.), and dash (-).'
        required: true
        schema:
          type: string
          maxLength: 128
        example: '5898781176487936'
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                example: 700;w=60;burst=75;w=1
                type: string
                format: quota-policy
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current time window
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds until reset of the current time window
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transactional_api.public.GetResponse'
              example:
                data:
                  campaign_id: '6239084716089344'
                  identifiers:
                  - email:
                      email: alice@gmail.com
                  product_ids:
                  - 27y9pconfyu7h
                  customer_attributes:
                    first_name:
                      string_value: Alice
                  name: namespaces/bluestore/messages/1231239
                  statuses:
                  - status: INITIATED
                    timestamp: '2026-01-01T00:00:00.00Z'
                  - status: SENT
                    timestamp: '2026-01-01T00:00:01.00Z'
                  - status: DELIVERED
                    timestamp: '2026-01-01T00:00:02.00Z'
        '404':
          description: Message not found for the provided id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
              example:
                code: 5
                message: 'we could not find a message matching that ID: 1231231'
                details: []
        '429':
          description: Too many requests
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                example: 700;w=60;burst=75;w=1
                type: string
                format: quota-policy
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current time window
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds until reset of the current time window
              schema:
                type: integer
          content:
            application/json: {}
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      security:
      - GlooAuth:
        - transactional.api
    post:
      tags:
      - Transactional
      summary: Send a transactional message
      operationId: Transactional_Send
      parameters:
      - name: namespace
        in: path
        description: The unique name of the Bluecore environment.
        required: true
        schema:
          type: string
        example: bluestore
      - name: id
        in: path
        required: true
        description: 'A client-generated unique identifier used for idempotency. Must be unique for each send request. Allowed characters:  alphanumeric, colon (:), underscore (_), period (.), and dash (-).'
        schema:
          type: string
          maxLength: 128
          example: '5898781176487936'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Transactional_Send_transactional_api.public.SendRequest'
        required: true
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                example: 700;w=60;burst=75;w=1
                type: string
                format: quota-policy
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current time window
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds until reset of the current time window
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transactional_api.public.SendResponse'
              examples:
                send_transactional_email:
                  summary: Email example
                  value:
                    data:
                      campaign_id: '6239084716089344'
                      identifiers:
                      - email:
                          email: alice@gmail.com
                      product_ids:
                      - 27y9pconfyu7h
                      use_draft: false
                      statuses:
                      - status: SENT
                        timestamp: '2026-01-01T00:00:00.00Z'
                send_transactional_sms:
                  summary: SMS/MMS example
                  value:
                    data:
                      campaign_id: '5227859897868288'
                      identifiers:
                      - phone_number:
                          phone_number: '+19293337777'
                      use_draft: true
                      body: Your order has shipped, {{first_name}}!
                      customer_attributes:
                        first_name:
                          string_value: Alice
                      statuses:
                      - status: SENT
                        timestamp: '2026-01-01T00:00:00.00Z'
        '400':
          description: Bad request. No response returned.
        '429':
          description: Too many requests
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                example: 700;w=60;burst=75;w=1
                type: string
                format: quota-policy
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current time window
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds until reset of the current time window
              schema:
                type: integer
          content:
            application/json: {}
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      security:
      - GlooAuth:
        - transactional.api
components:
  schemas:
    google.rpc.Status:
      type: object
      properties:
        code:
          type: integer
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/google.protobuf.Any'
          description: A list of messages that carry the error details.  There is a common set of message types for APIs to use.
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
    transactional_api.public.Identifier:
      type: object
      allOf:
      - oneOf:
        - title: email
          type: object
          properties:
            email:
              example: alice@gmail.com
              maxLength: 254
              type: string
              description: The primary identifier that represents the customer’s email address. See [Email address](https://developers.bluecore.com/docs/email-address#/) for information on how they are normalized and validated.
              format: email
        - title: phone_number
          type: object
          properties:
            phone_number:
              example: '+15556667777'
              pattern: ^\+?[1-9]\d{0,14}$
              type: string
              description: The secondary identifier that represents the customer’s phone number. E.164 format.
              format: e.164
    transactional_api.public.GetResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/transactional_api.public.TransactionalMessage'
    transactional_api.public.StatusEvent:
      type: object
      properties:
        status:
          enum:
          - INITIATED
          - HALTED
          - SENT
          - DELIVERED
          - DELIVERY_FAILURE
          - TEMPLATE_PARAMETERS_UPDATED
          type: string
          format: enum
        timestamp:
          type: string
          format: date-time
        details:
          type: string
          description: Only populated for halt or delivery failures
    Transactional_Send_transactional_api.public.SendRequest:
      required:
      - message
      type: object
      properties:
        message:
          $ref: '#/components/schemas/transactional_api.public.TransactionalMessage'
    transactional_api.public.SendResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/transactional_api.public.TransactionalMessage'
    customers.AttributeValue:
      type: object
      allOf:
      - oneOf:
        - title: string_value
          type: object
          properties:
            string_value:
              type: string
              description: A string value.
        - title: number_value
          type: object
          properties:
            number_value:
              type: number
              description: A floating point number.
              format: double
        - title: bool_value
          type: object
          properties:
            bool_value:
              type: boolean
              description: A boolean value.
        - title: time_value
          type: object
          properties:
            time_value:
              type: string
              description: 'A timestamp of the recorded activity, using [RFC 3339 format](https://www.ietf.org/rfc/rfc3339.txt).


                Example: January 1, 2025 5:00:00 UTC is represented as `2025-01-01T05:00:00.00Z`'
              format: date-time
        - title: int_value
          type: object
          properties:
            int_value:
              type: string
              description: 'A 64-bit integer.


                Sent as a string to preserve accuracy for numbers above 53 bits.'
      description: Attribute values can be any type supported by JSON, with the addition of timestamps
    google.protobuf.Any:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
    transactional_api.public.TransactionalMessage:
      required:
      - identifiers
      - campaign_ids
      type: object
      properties:
        identifiers:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/transactional_api.public.Identifier'
        campaign_ids:
          minItems: 1
          type: array
          items:
            type: string
          description: The unique ID associated with the Bluecore campaign. This ID appears in the URL for the campaign in Bluecore. If multiple `campaign_ids` are sent, the message sends to all campaigns and the response includes a `campaign_id` for each campaign the message sent to.
        product_ids:
          type: array
          items:
            type: string
          description: List of product IDs used as input products if the campaign uses a product-based recipe rule, such as co-recommendations.
        customer_attributes:
          type: object
          description: A JSON-formatted object of key/value pairs associated with the customer profile and can be referenced in the email body. Each attribute must be in `snake_case`.
          additionalProperties:
            $ref: '#/components/schemas/customers.AttributeValue'
        use_draft:
          type: boolean
          description: If `true`, the draft version of the campaign sends, if available. If you send `true` and no draft is available, the live campaign sends. If `false`, the live version of the campaign sends.  Defaults to `false`.
        name:
          readOnly: true
          type: string
          description: The resource name.
        body:
          readOnly: true
          type: string
          description: The body of the campaign that was sent to the customer. Only populated for SMS/MMS campaigns.
        campaign_id:
          readOnly: true
          type: string
          description: The unique ID associated with the transactional campaign used to send.
        statuses:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/transactional_api.public.StatusEvent'
          description: The status associated with that send, sorted by ascending timestamp. For more information on status definitions and next steps, see [Transactional message statuses](https://developers.bluecore.com/reference/transactional-message-statuses).
  securitySchemes:
    GlooAuth:
      type: apiKey
      in: header
      name: authorization
      description: Value for the authorization header will be Bearer followed by the token generated with the [Get access token](https://developers.bluecore.com/reference/authn_getaccesstoken#/) call.
      x-default: Bearer token