inboxes

Update inbox

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

patch/v1/inboxes/{id}

Request

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

Path parameters

idstring required

Request body

displayNamestring nullable

Sender display name. Set null to clear.

webhookUrlstring 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.

forwardTostring 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

Inbox updated

idstring

OpenMail inbox ID

podIdstring

ID of the pod this inbox belongs to. Inboxes created without an explicit pod land in your account's default pod.

addressstring email

Full email address

displayNamestring nullable

Sender display name

webhookUrlstring nullable

URL that receives signed webhook events for this inbox, if set. Overrides the account-level webhook for this inbox only.

webhookSecretstring 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.

forwardTostring 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.

createdAtstring date-time

Changes

No recorded changes to this operation across all 1 revision of this API.