---
title: "Update inbox"
method: PATCH
path: "/v1/inboxes/{id}"
tags: ["inboxes"]
---

# Update inbox

`PATCH /v1/inboxes/{id}`

## Request

- Base URL: `https://api.openmail.sh`
- URL: `https://api.openmail.sh/v1/inboxes/{id}`
- Auth: HTTP bearer

Update an inbox's settings, such as the sender display name shown in the From header.

## Path parameters

- `id` string, required

## Request body

- object
  - `displayName` string, nullable: Sender display name. Set null to clear.
  - `webhookUrl` string, nullable: URL to receive signed webhook events for this inbox. Set null to clear and revert to the account-level webhook. A signing secret is generated the first time a webhook URL is set on this inbox and returned once in the response body.
  - `forwardTo` string, nullable: Email address that receives a copy of inbound messages, e.g. your own Gmail. Members of your organisation are confirmed at once; any other address is emailed a confirmation link and `forwardStatus` stays `pending` until they click it. Re-sending the same pending address re-issues the link. Setting a new address also re-enables forwarding that was paused for bouncing. Set null to stop forwarding.
  - `forwardWhen` 'always' | 'needs_human' | 'webhook_failed' | 'null', nullable: When to forward. `always` (default); `needs_human` only mail the agent should not auto-handle (`autoReplyable` false); `webhook_failed` only once webhook delivery has exhausted its retries or there was no webhook or WebSocket to deliver to.

## Response `200`

Inbox updated

- Inbox
  - `id` string: OpenMail inbox ID
  - `podId` string: ID of the pod this inbox belongs to. Inboxes created without an explicit pod land in your account's default pod.
  - `address` string, email: Full email address
  - `displayName` string, nullable: Sender display name
  - `webhookUrl` string, nullable: URL that receives signed webhook events for this inbox, if set. Overrides the account-level webhook for this inbox only.
  - `webhookSecret` string, nullable: Signing secret for this inbox's webhook. Only present in the response when the secret is generated or rotated (on create, on first setting a webhook URL, or via the rotate-secret endpoint) — it is never returned afterward.
  - `forwardTo` string, nullable: Address that receives copies of this inbox's inbound mail, if set.
  - `forwardWhen` 'always' | 'needs_human' | 'webhook_failed' | 'null', nullable: Which inbound mail is forwarded. Null when forwarding is not set.
  - `forwardStatus` 'pending' | 'active' | 'disabled' | 'null', nullable: `pending` until the address confirms via the emailed link (members of your organisation are confirmed at once); `active` once copies are flowing; `disabled` when forwarding paused itself after the address hard-bounced repeatedly or complained — set `forwardTo` again to resume. Null when forwarding is not set.
  - `createdAt` string, date-time

## Other responses

- `403`: The authenticating key is inbox-scoped (read + send only) and cannot modify the inbox
- `404`: Not found
- `422`: `webhookUrl` failed validation (`invalid_webhook_url`), or forwarding settings were rejected (`invalid_forward_to`, `forward_to_is_openmail_address`, `forward_verification_cooldown`, `invalid_forward_when`, `forward_when_requires_forward_to`)
- `429`: 10 forwarding confirmation emails already sent this hour (`forward_verification_limit`)

---

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