---
title: "POST /v1/workspaces/{workspaceId}/transactional-sends"
method: POST
path: "/v1/workspaces/{workspaceId}/transactional-sends"
---

# POST /v1/workspaces/{workspaceId}/transactional-sends

`POST /v1/workspaces/{workspaceId}/transactional-sends`

## Request

- Base URL: `https://api.bangermail.com`
- URL: `https://api.bangermail.com/v1/workspaces/{workspaceId}/transactional-sends`
- Auth: HTTP bearer

One recipient per Journey send. To takes one recipient in any RecipientInput shape ("a@example.com", "Pat <a@example.com>", { email, name }, or a one-element list); Cc and Bcc must be empty. reply_to defaults to the Journey's mailbox (an empty list also means the default); Product email needs exactly one. A new API Journey defaults to managed source content; legacy code Journeys retain complete-content sends. A refusal (4xx) leaves nothing frozen for the recipient, so a corrected call with a new idempotency key sends.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `journey` string: Key of the Journey this email belongs to, such as welcome. A key Banger has not seen yet records a new Journey from this email and sends it; claim that Journey later to manage its content. The key of a Journey you created sends once that Journey is approved and on. Without a key the send is refused with 422 journey_key_required, unless the workspace accepts sends without one. POST /journeys/{journeyKey}/send is the same send with the key in the path.
  - `mailbox_id` string, uuid: Sender mailbox. Optional when the named Journey has one, which then sends.
  - `to` union, required: Recipients for to, cc, bcc and reply_to: an address ("a@example.com" or "Pat <a@example.com>"), an { email, name } object, or a list mixing both. Banger stores them as { email, name } objects with the email lowercased. The idempotency hash covers the body as sent, so retry with the same shape.
    - string
    - Participant
      - `name` string
      - `email` string, email, required
    - union[]
      - union
        - string
        - Participant
          - `name` string
          - `email` string, email, required
  - `cc` Participant[]
    - `name` string
    - `email` string, email, required
  - `bcc` Participant[]
    - `name` string
    - `email` string, email, required
  - `subject` string
  - `expires_at` string, date-time: Discard a deferred Journey send after this instant; at most seven days from the original request.
  - `expires_after_seconds` integer
  - `body_text` string
  - `body_html` string
  - `reply_to` union: Recipients for to, cc, bcc and reply_to: an address ("a@example.com" or "Pat <a@example.com>"), an { email, name } object, or a list mixing both. Banger stores them as { email, name } objects with the email lowercased. The idempotency hash covers the body as sent, so retry with the same shape.
    - string
    - Participant
      - `name` string
      - `email` string, email, required
    - union[]
      - union
        - string
        - Participant
          - `name` string
          - `email` string, email, required
  - `headers` object
  - `tags` object[]
    - `name` string, required
    - `value` string, required

## Response `202`

Successful response.

- object
  - `data` JourneySendReceipt, required
    - `action_kind` 'transactional.send', required
    - `id` string, uuid
    - `send_intent_id` string, uuid
    - `provider_attempt_id` string, uuid
    - `status` string, required: sent/queued states from delivery, or for a frozen request: deferred (scheduled by policy or a translation wait), processing (being sent), discarded.
    - `replayed` boolean
    - `journey` object, nullable, required
      - `journey_id` string, uuid, required
      - `enrollment_id` string, uuid, required
      - `step_id` string, uuid, required
      - `step_position` integer, required
      - `origin` 'journey'
      - `journey_identity` string
    - `ignored_variables` string[], required
    - `scheduled_at` string, date-time
    - `reason` string
    - `communication_reservation_id` string, uuid

## Other responses

- `409`: `journey_review_required`: the named Journey is one you created and it is not on yet; request its activation with POST /approvals (`action_kind: "sequence.activate"`), which a person approves in Banger. `journey_send_changed_while_deferred`: this recipient's earlier send on the Journey is still scheduled, or was frozen for sending in the last ten minutes, with a different request. Retry that request with its original idempotency key and payload, or wait. A send that failed before Banger accepted it never blocks later calls. `idempotency_conflict`: the key was used with a different payload.
- `422`: `journey_key_required`: name the Journey with `journey`. `product_reply_to_required`: Product email needs exactly one Reply-To address. Nothing is recorded for the recipient when the payload is rejected.

---

[API](https://skmtc.dev/bangermail/apis/banger-api.md) · [All operations](https://skmtc.dev/bangermail/apis/banger-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bangermail/apis/banger-api/revisions/a149909267f9?raw)