Mail handling API

Manage mailbox forwarding

Scope: mailbox_forwarding:read for GET and mailbox_forwarding:write for create and delete. A mailbox can have up to three pending or active destinations.

Creating a destination sends a 24-hour confirmation link to that address and returns a pending object. Forwarding starts only after the recipient confirms. Messages keep a local copy, and spam is filtered before forwarding. Set sender to one exact From address to forward only that sender, or omit it to forward every non-spam message. Set recipient to the mailbox's primary address or alias to forward only mail delivered there. Omit it to match every address. If both fields are set, a message must match both. Self-forwarding and multi-mailbox delivery loops are rejected.

Create request

{
  "destination": "owner@example.net",
  "sender": "newsletter@example.com",
  "recipient": "nabeel@example.com"
}

List response

{
  "object": "mailbox_forwarding_list",
  "mailbox_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "data": [
    {
      "object": "mailbox_forwarding",
      "id": "fwd_0123456789abcdefghjkmnpq",
      "mailbox_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "destination": "owner@example.net",
      "sender": "newsletter@example.com",
      "recipient": "nabeel@example.com",
      "status": "pending",
      "verification_sent_at": "2026-07-13T12:00:00.000Z",
      "verified_at": null,
      "created_at": "2026-07-13T12:00:00.000Z",
      "updated_at": "2026-07-13T12:00:00.000Z"
    }
  ]
}

Examples

curl -X POST https://shipmail.to/api/v1/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/forwarding \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"destination":"owner@example.net","sender":"newsletter@example.com","recipient":"nabeel@example.com"}'

curl https://shipmail.to/api/v1/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/forwarding \
  -H "Authorization: Bearer sm_live_..."

curl -X DELETE https://shipmail.to/api/v1/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/forwarding/fwd_0123456789abcdefghjkmnpq \
  -H "Authorization: Bearer sm_live_..."

Update auto-reply

Scope: mailboxes:write. Rate limit tier: write. Configure an automatic reply (vacation/out-of-office) for a mailbox. Each sender receives the auto-reply at most once every 7 days, even if they email again in that window. While its out-of-office window is active, delivery routing skips this mailbox for new selections. Existing conversations remain here.

Request body

Example

curl -X PATCH https://shipmail.to/api/v1/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/auto-reply \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "body": "I am away until January 6. I will reply when I return.",
    "from_date": "2026-12-23T00:00:00Z",
    "to_date": "2027-01-06T00:00:00Z"
  }'

Returns the updated mailbox object.

Configure delivery routing

Read with mailboxes:read and update with mailboxes:write. Routing applies once, when a new conversation arrives at the mailbox's primary or plus-primary address. Mail sent to an alias, plus-alias, or catch-all identity bypasses routing and stays dedicated to that address. Later messages in a routed conversation return to the same destination mailbox.

Use keep to deliver here, fixed for one destination, or round_robin for at least two ordered destinations. Fixed and round-robin modes require an explicit fallback mailbox. The source mailbox may be both a destination and the fallback. An active out-of-office destination is skipped for new selections. If every normal destination is unavailable, the fallback receives the message.

Round-robin example

curl -X PATCH https://shipmail.to/api/v1/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/delivery-routing \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "round_robin",
    "destination_mailbox_ids": [
      "11111111-1111-4111-8111-111111111111",
      "22222222-2222-4222-8222-222222222222"
    ],
    "fallback_mailbox_id": "33333333-3333-4333-8333-333333333333"
  }'

The response includes every eligible destination and the saved mode. An automatic route initially reports pending, then active after the mail-routing cache synchronizes. A routed conversation with no reply, assignment, or note after 24 hours stays in its destination and alerts the people who can access that mailbox.