Transactional senders

Before you start

• The transactional domain must be verified.
• Writes need mailboxes:write, and the key must act for an Owner or Admin with access to every mailbox. The key must also reach the reply mailbox and, to create a sender, its transactional domain: a key limited to mailboxes cannot create one.
• Lists and reads show only senders whose reply mailbox the key can reach. Any other sender reads as not found.
• Setup steps have their own limits per key: 30 creates and 30 moves per hour, and 60 changes of state or refuse_disposable per hour.

The transactional sender object

{
  "object": "transactional_sender",
  "id": "txbind_0123456789abcdefghjkmnpq",
  "from": "hello@mail.example.com",
  "display_name": "Acme",
  "domain_id": "txdom_0123456789abcdefghjkmnpq",
  "mailbox_id": "550e8400-e29b-41d4-a716-446655440000",
  "reply_to": "support@example.com",
  "state": "active",
  "refuse_disposable": false,
  "smtp_enabled": false,
  "created_at": "2026-11-08T09:00:00.000Z"
}

List transactional senders

Returns { "object": "list", "data": [...] } without pagination. Pass domain_id=txdom_... to list the senders of one domain.

Create a transactional sender

{
  "domain_id": "txdom_0123456789abcdefghjkmnpq",
  "mailbox_id": "550e8400-e29b-41d4-a716-446655440000",
  "local_part": "hello",
  "display_name": "Acme"
}

local_part is the part before @, so hello on mail.example.com sends as hello@mail.example.com. display_name is 1 to 100 characters without line breaks. mailbox_id is the mailbox that gets replies: its address becomes the sender's Reply-To for every send that sets none. Returns 201 with the sender, which can send at once.

To check it, send yourself one email from it with POST /v1/messages. It counts as one live send.

Retrieve a transactional sender

Returns the sender.

Update a transactional sender

{
  "state": "disabled"
}

Send at least one of these fields:

• state: active or disabled. A disabled sender refuses sends, and its SMTP credentials cannot send, until you turn it back on.
• mailbox_id: move replies to another mailbox. The sender's Reply-To changes with it.
• refuse_disposable: true to refuse sends to temporary email addresses.

Shipmail applies a move first, then state, then refuse_disposable. Each is its own step: if one fails, the earlier ones stay applied. Returns the updated sender.

There is no delete. Turn a sender off with state set to disabled.

Errors

Errors use the standard error envelope. Branch on details[0].code, not on the message.