Skip to main content
An inbox is a unique email address assigned to an agent. When you create an inbox, the agent can immediately send and receive email from that address.

​
Address format

Inboxes use the openmail.sh domain:
For example: support@openmail.sh
  • If you provide a mailboxName, it becomes the local part of the address
  • If you omit it, we generate a random 8-character alphanumeric string
  • Mailbox names must be 3–30 characters, lowercase alphanumeric with dots and hyphens allowed
Need your own domain (e.g. agent@yourdomain.com)? See Custom domains.

​
Sender name

Set displayName when creating or updating an inbox to control how recipients see the sender. Without a display name, recipients see the raw email address. With a display name, the From header becomes Name <address>.
Recipients will see John Smith instead of the raw email address. You can update the display name at any time with PATCH /v1/inboxes/:id.

​
Multi-tenant routing

Route inbound events by inbox_id. Map each inbox ID to your user/agent/container in your app. Multi-tenant - One account, many inboxes. Create one inbox per agent and route by inbox_id. To confine an agent to the single inbox it owns, give it an inbox-scoped API key. To isolate a tenant that owns several inboxes, see the Multi-tenancy guide. Multiple inboxes per user - You can create multiple inboxes for the same user. Webhooks include inbox_id so you can identify which inbox received the message.
See Email deliverability for warm-up schedules and content best practices.

​
Inbox-scoped API keys

Your account-wide key reaches every inbox. When one agent owns exactly one inbox, hand it an inbox-scoped key instead — the narrowest scope OpenMail offers:
  • It can read and send from that one inbox, including its threads, messages, and drafts. Every other inbox is invisible to it — even listing inboxes returns only the one it owns.
  • It is read and send only. It cannot create, modify, or delete inboxes, and cannot rotate a webhook secret.
  • It cannot mint or revoke keys, so a leaked key cannot widen its own reach.
Anything outside that boundary is refused rather than silently ignored — see forbidden if you need to handle it. Minting requires an account-wide key — a pod- or inbox-scoped key cannot mint. The full token is returned once, at creation, and cannot be retrieved again. Listing returns only a masked tokenPrefix and last4.
Each inbox allows up to 20 active keys; revoke an unused one to free a slot. Revoking takes effect immediately, on the key’s very next request. Deleting an inbox also revokes every key scoped to it. On WebSockets, a connection authenticated with an inbox-scoped key streams only that inbox’s events, so a subscribe-all needs no filtering on your side. Choosing between scopes? See Key scopes for the full comparison.

​
Limits

​
Lifecycle

Deleting an inbox (DELETE /v1/inboxes/:id) permanently removes the inbox and all associated messages, threads, and attachments. This is not reversible.