generated: '2026-07-18'
method: searched
source: https://developers.bluecore.com/
docs:
- https://developers.bluecore.com/docs/rate-limiting
- https://developers.bluecore.com/docs/error-codes
- https://developers.bluecore.com/reference/transactional_send
authentication:
  style: oauth2-client-credentials-bearer
  header: authorization
  value: Bearer <access_token>
  see: authentication/bluecore-authentication.yml
idempotency:
  supported: true
  mechanism: path-parameter
  parameter: id
  applies_to:
  - Transactional_Send
  detail: >-
    The transactional send endpoint takes a client-generated unique identifier as the
    `{id}` path segment (POST /namespaces/{namespace}/transactional-messages/{id}) that
    is used as an idempotency key; it must be unique for each send request. Allowed
    characters: alphanumeric, colon (:), underscore (_), period (.), and dash (-),
    max length 128. The same id is used with Transactional_Get to retrieve the message
    status history. Replaying a previously used id conflicts (HTTP 409).
  retention: not-documented
pagination:
  supported: false
  detail: No collection/list endpoints are published; all read endpoints resolve a single resource by identifier.
request_tracing:
  header: x-bluecore-id
  detail: >-
    Responses on the customer and eligibility endpoints return an `x-bluecore-id` header,
    a request id used to trace logs for that request. Include it (or the `request_id` in a
    5xx error body) when contacting support@bluecore.com.
versioning:
  scheme: none-in-path
  detail: >-
    No version segment in the API path (base https://a.bluecore.com/api). The published
    per-operation OpenAPI documents carry info.version 0.0.1; the APIs are labelled beta.
error_envelope:
  format: google.rpc.Status
  media_type: application/json
  fields: [code, message, details]
  detail: >-
    Errors return a google.rpc.Status object (integer `code`, developer-facing `message`,
    and a `details[]` array of google.protobuf.Any). This is Google API error model, not
    RFC 9457 problem+json. See errors/bluecore-problem-types.yml.
rate_limit_signaling:
  headers:
  - RateLimit-Limit
  - RateLimit-Remaining
  - RateLimit-Reset
  spec_headers:
  - x-ratelimit-limit
  - x-ratelimit-remaining
  - x-ratelimit-reset
  algorithm: fixed-window (burst 1s + steady 1m)
  quota_policy_example: 700;w=60;burst=75;w=1
  see: rate-limits/bluecore-rate-limits.yml
content_type:
  request: application/json
  note: A 406 is returned when the content-type header is not application/json.
retry_policy:
  documented: true
  strategy: exponential-backoff
  min_backoff: 30s
  max_backoff: 300s
  max_retries: 5
  source: https://www.bluecore.com/transactional-api-docs/
  detail: >-
    Bluecore's published transactional API documentation states: "Bluecore recommends retrying API
    calls with an exponential backoff, starting with the minimum backoff of 30 seconds and maximum
    backoff of at least five minutes, for a maximum of five retries." Applies to the retryable
    5xx classes (500 function timeout, 502, 503, 504).
payload_limits:
  max_request_body: 900 KB
  max_template_attributes: 819200 bytes
  source: https://www.bluecore.com/transactional-api-docs/
  detail: >-
    From the legacy transactional API contract: total payload must be under 900 KB and a
    `Template attribute size exceeds the maximum allowed (819,200 bytes)` 422 is returned when the
    template_attributes object is oversized.
test_mode:
  sandbox_environment: false
  mechanism: draft-campaign flag
  parameter: use_draft
  detail: >-
    Bluecore publishes no sandbox environment, no test-vs-live key prefixes and no magic test
    identifiers, so no sandbox/ artifact is emitted. The only documented test facility is the
    legacy transactional send's boolean `use_draft` flag, which sends against the draft version of
    a campaign rather than the live one ("trigger transactional or real-time welcome emails for
    both tests and live sends"). Sends still go to a real recipient address.
surface_divergence:
  detail: >-
    Bluecore runs three separately-documented API surfaces with three different auth models and
    three different hosts. An integrator cannot carry conventions from one to the next.
  surfaces:
  - {name: Developer API, host: 'https://a.bluecore.com/api', auth: 'OAuth 2.0 client-credentials Bearer',
     docs: 'https://developers.bluecore.com/', status: beta}
  - {name: Transactional API (legacy), host: 'https://api.bluecore.com/email/',
     auth: 'static customer-specific API key, Authorization: Bearer',
     docs: 'https://www.bluecore.com/transactional-api-docs/', status: 'legacy — Bluecore states it is migrating away from this API'}
  - {name: Events API, host: 'https://api.bluecore.app/api/track/mobile/v1',
     auth: 'tenant token inside the JSON body (properties.token)',
     docs: 'https://help.bluecore.com/help/events-api', status: current}