---
title: "Update mailbox delivery routing"
method: PATCH
path: "/mailboxes/{id}/delivery-routing"
tags: ["Mailboxes"]
---

# Update mailbox delivery routing

`PATCH /mailboxes/{id}/delivery-routing`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/mailboxes/{id}/delivery-routing`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

Choose whether new primary-address conversations stay in this mailbox, go to one mailbox, or rotate among mailboxes. Fixed and round-robin routing require an explicit fallback mailbox; the source mailbox may also be a normal destination. A destination that is out of office is skipped for new selections; existing conversation affinity is preserved.

## Headers

- `X-Shipmail-Organization` string

## Request body

- union
  - object
    - `mode` 'keep', required
  - object
    - `mode` 'fixed', required
    - `destination_mailbox_id` string, required
    - `fallback_mailbox_id` string, required
  - object
    - `mode` 'round_robin', required
    - `destination_mailbox_ids` string[], required
    - `fallback_mailbox_id` string, required

## Response `200`

Updated mailbox delivery routing. Pending routes become active after the mail routing cache has synchronized.

- union
  - object
    - `object` 'mailbox_delivery_routing', required
    - `mailbox_id` string, required
    - `source_address` string, email, required
    - `destinations` MailboxDeliveryDestination[], required
      - `id` string, required
      - `address` string, email, required
      - `display_name` string, nullable, required
      - `status` 'available' | 'out_of_office' | 'suspended' | 'archived' | 'unavailable', required
      - `out_of_office_end_at` string, date-time, nullable, required
      - `responsible_member_count` integer, required
      - `push_ready_member_count` integer, required
    - `mode` 'keep', required
  - object
    - `object` 'mailbox_delivery_routing', required
    - `mailbox_id` string, required
    - `source_address` string, email, required
    - `destinations` MailboxDeliveryDestination[], required
      - `id` string, required
      - `address` string, email, required
      - `display_name` string, nullable, required
      - `status` 'available' | 'out_of_office' | 'suspended' | 'archived' | 'unavailable', required
      - `out_of_office_end_at` string, date-time, nullable, required
      - `responsible_member_count` integer, required
      - `push_ready_member_count` integer, required
    - `mode` 'fixed', required
    - `destination_mailbox_id` string, required
    - `fallback_mailbox_id` string, required
    - `activation_state` 'pending' | 'active' | 'failed', required
    - `activation_error` string, nullable, required
  - object
    - `object` 'mailbox_delivery_routing', required
    - `mailbox_id` string, required
    - `source_address` string, email, required
    - `destinations` MailboxDeliveryDestination[], required
      - `id` string, required
      - `address` string, email, required
      - `display_name` string, nullable, required
      - `status` 'available' | 'out_of_office' | 'suspended' | 'archived' | 'unavailable', required
      - `out_of_office_end_at` string, date-time, nullable, required
      - `responsible_member_count` integer, required
      - `push_ready_member_count` integer, required
    - `mode` 'round_robin', required
    - `destination_mailbox_ids` string[], required
    - `fallback_mailbox_id` string, required
    - `activation_state` 'pending' | 'active' | 'failed', required
    - `activation_error` string, nullable, required

## Other responses

- `401`: Authentication failed.
- `403`: Insufficient permissions.
- `404`: Resource not found.
- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

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