---
title: "POST /v1/workspaces/{workspaceId}/sending-domains"
method: POST
path: "/v1/workspaces/{workspaceId}/sending-domains"
---

# POST /v1/workspaces/{workspaceId}/sending-domains

`POST /v1/workspaces/{workspaceId}/sending-domains`

## Request

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

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `domain` string, required: The product's exact domain or subdomain. By default Banger derives three separate lane subdomains.
  - `setup_mode` 'simple' | 'advanced': Simple provisions one mailbox transport for receiving and sending from selected mailbox addresses, including Broadcasts and Journeys. Advanced provisions separate sending lanes.
  - `mailbox_mode` 'subdomain' | 'migrate': Simple setup defaults to the root when no mailbox prefix is supplied; advanced defaults to a subdomain. Subdomain preserves existing domain mail. Migrate requests Mailboxes at the exact domain. An occupied exact domain or lane requires a request through sending-domain-migrations followed by authorization in the signed-in Banger Approvals panel. Agent credentials cannot authorize migration. No old messages are imported and DNS is never changed automatically.
  - `root_dmarc_confirmed` boolean: Legacy compatibility field; existing policies are preserved and setup requires no confirmation.
  - `lane_prefixes` object
    - `mailbox` string
    - `product` string
    - `broadcast` string
  - `route_providers` object: Resend is accepted only when Banger already detected it in this domain's DNS and the selected product has an active connection. Clients must never advertise it otherwise.
    - `product` 'banger' | 'resend'
    - `broadcast` 'banger' | 'resend'
  - `route_domains` object: Exact verified domains synchronized from Resend. Required for each lane that keeps Resend.
    - `product` string
    - `broadcast` string

## Response `200`

Idempotent replay of a Banger-native sending-domain request.

- object
  - `data` NativeSendingDomain, required
    - `domain_id` string, uuid, required
    - `product_id` string, uuid, required
    - `root_domain` string, required
    - `parent_domain` string: Company domain retained when a lane uses a subdomain.
    - `setup_mode` 'simple' | 'advanced'
    - `domain_status` 'pending' | 'verified' | 'failed' | 'disabled' | 'deleting' | 'deleted', required
    - `lanes` NativeSendingLane[], required
      - `id` string, uuid, required
      - `created_at` string, date-time
      - `kind` 'mailbox' | 'product' | 'broadcast', required
      - `display_name` string, required
      - `from_domain` string, required
      - `mail_from_domain` string, nullable, required
      - `inbound_domain` string, nullable, required
      - `route_provider` 'banger' | 'resend', required
      - `selected_provider_connection_id` string, uuid, nullable, required
      - `inbound_provider` 'banger' | 'null', nullable, required
      - `status` 'pending' | 'active' | 'paused' | 'deleting' | 'deleted', required
      - `status_reason` string, nullable, required
      - `desired_revision` integer, required
      - `observed_revision` integer, required
      - `dns_ready` boolean, required
      - `provider_ready` boolean, required
      - `inbound_ready` boolean, required
      - `outbound_ready` boolean, required
      - `banger_transport_ready` boolean, required
      - `banger_mail_from_domain` string, nullable, required
      - `provisioning_job_id` string, uuid, nullable, required
      - `provisioning_status` 'pending' | 'provisioning' | 'waiting_dns' | 'active' | 'failed' | 'deleting' | 'deleted' | 'not_required', required
      - `provisioning_error_code` string, nullable
      - `provisioning_next_attempt_at` string, nullable
      - `provisioning_last_checked_at` string, nullable
      - `provider_identity_status` string, nullable
      - `provider_dkim_status` string, nullable
      - `dns_records` NativeSendingDnsRecord[], required
        - `id` string, uuid, required
        - `lane_id` string, uuid, required
        - `provider` 'banger' | 'resend', required
        - `purpose` string, required
        - `type` 'TXT' | 'MX' | 'CNAME', required
        - `name` string, required
        - `value` string, required
        - `priority` integer, nullable, required
        - `required` boolean, required
        - `status` 'pending' | 'verified' | 'error', required
        - `provider_status` 'pending' | 'verified' | 'error' | 'not_applicable', required
        - `first_observed_at` string, date-time, nullable, required
        - `last_checked_at` string, date-time, nullable, required
        - `error` object, required
        - `provider_reference` string, nullable, required
    - `dns_records` NativeSendingDnsRecord[], required
      - `id` string, uuid, required
      - `lane_id` string, uuid, required
      - `provider` 'banger' | 'resend', required
      - `purpose` string, required
      - `type` 'TXT' | 'MX' | 'CNAME', required
      - `name` string, required
      - `value` string, required
      - `priority` integer, nullable, required
      - `required` boolean, required
      - `status` 'pending' | 'verified' | 'error', required
      - `provider_status` 'pending' | 'verified' | 'error' | 'not_applicable', required
      - `first_observed_at` string, date-time, nullable, required
      - `last_checked_at` string, date-time, nullable, required
      - `error` object, required
      - `provider_reference` string, nullable, required
    - `deletion` object, nullable, required
      - `job_id` string, uuid, required
      - `status` 'pending' | 'processing' | 'waiting_provider' | 'completed' | 'failed', required
      - `last_error_code` string, nullable, required
      - `cleanup_records` NativeSendingDnsRecord[], required: Exact DNS records the user may remove after teardown completes.
        - `id` string, uuid, required
        - `lane_id` string, uuid, required
        - `provider` 'banger' | 'resend', required
        - `purpose` string, required
        - `type` 'TXT' | 'MX' | 'CNAME', required
        - `name` string, required
        - `value` string, required
        - `priority` integer, nullable, required
        - `required` boolean, required
        - `status` 'pending' | 'verified' | 'error', required
        - `provider_status` 'pending' | 'verified' | 'error' | 'not_applicable', required
        - `first_observed_at` string, date-time, nullable, required
        - `last_checked_at` string, date-time, nullable, required
        - `error` object, required
        - `provider_reference` string, nullable, required

## Other responses

- `202`: The three canonical lanes were saved and queued for resumable provisioning.

---

[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)