# OpenMail - [Welcome](https://docs.openmail.sh/index.md): Welcome to OpenMail — email infrastructure for AI agents. Start with the quickstart, explore core concepts, or jump straight into the API reference. - [Quickstart](https://docs.openmail.sh/quickstart.md): Get your AI agent its own email address. Pick your agent framework and follow its setup guide to create an inbox and start sending and receiving email in minutes. - [Inboxes](https://docs.openmail.sh/concepts/inboxes.md): Every OpenMail agent gets a dedicated email address and inbox. Learn how to create, configure, and manage inboxes via API or CLI. - [Pods](https://docs.openmail.sh/concepts/pods.md): Pods are isolated sub-accounts inside your OpenMail account. Use them to keep each of your end users or tenants separate while billing stays on one account. - [Custom domains](https://docs.openmail.sh/concepts/custom-domains.md): Send and receive email from your own domain with OpenMail. Learn how to configure DNS records, verify ownership, and enable custom domain routing. - [Threading](https://docs.openmail.sh/concepts/threading.md): OpenMail automatically groups emails into threads by subject and message headers. Learn how threading works and how to read or update thread state. - [Attachments](https://docs.openmail.sh/concepts/attachments.md): Send files with outbound emails and access attachments on inbound messages. OpenMail parses and stores attachments, making them available via API. - [Suppressions](https://docs.openmail.sh/concepts/suppressions.md): OpenMail automatically suppresses sending to addresses that have bounced or unsubscribed. Learn how suppressions work and how to manage the list. - [Sender rules](https://docs.openmail.sh/concepts/sender-rules.md): Control who your inboxes may receive from and who they may send to. OpenMail enforces scoped allow and block rules on inbound delivery and every outbound send. - [Rate limits](https://docs.openmail.sh/concepts/rate-limits.md): OpenMail enforces per-inbox send limits and a cold-outreach cap on new recipients to protect deliverability. Learn how the limits are counted and how to stay within them. - [Overview](https://docs.openmail.sh/concepts/websockets.md): OpenMail WebSockets deliver email events in real time with sub-second latency. Learn how the persistent connection model works and when to use it. - [Quickstart](https://docs.openmail.sh/guides/websockets/quickstart.md): Connect to OpenMail's WebSocket endpoint and start receiving inbound email events in real time. Step-by-step guide with authentication and code examples. - [Protocol reference](https://docs.openmail.sh/pages/websockets/protocol.md): OpenMail WebSocket protocol reference — message types, subscribe payloads, event replay options, and connection lifecycle management. - [Overview](https://docs.openmail.sh/concepts/webhooks.md): OpenMail webhooks deliver inbound email events to your endpoint in real time. Learn about delivery semantics, headers, signature verification, and retries. - [Events](https://docs.openmail.sh/pages/webhooks/events.md): OpenMail webhook event reference — event types, full payload structure, and field descriptions for inbound email and reputation lifecycle (inbox/pod suspension and reactivation) events. - [Setup](https://docs.openmail.sh/guides/webhooks.md): Configure webhook endpoints to receive inbound email events from OpenMail in real time. Covers endpoint setup, payload format, and signature verification. - [Verification](https://docs.openmail.sh/pages/webhooks/verification.md): Verify OpenMail webhook payloads using HMAC-SHA256 signatures. Step-by-step examples for checking signatures and preventing replay attacks. - [API integration](https://docs.openmail.sh/guides/api-integration.md): Create and manage inboxes programmatically via the OpenMail REST API. Ideal for multi-tenant apps, agent orchestration frameworks, and CI pipelines. - [Multi-tenancy](https://docs.openmail.sh/guides/multi-tenancy.md): Onboard a tenant end-to-end: create a pod, provision inboxes, and hand the tenant a pod-scoped API key that can only reach its own inboxes. - [MCP server](https://docs.openmail.sh/integrations/mcp.md): Connect ChatGPT, Claude, Cursor, or any MCP client to OpenMail. One hosted URL gives your agent an inbox so it can read, send, and reply to email. - [OpenClaw](https://docs.openmail.sh/integrations/openclaw.md): Give your OpenClaw agent an email address. - [Hermes Agent](https://docs.openmail.sh/integrations/hermes.md): Give your Hermes agent an email address. - [Claude Code](https://docs.openmail.sh/integrations/claude-code.md): Give your Claude Code agent a real email address. Install the OpenMail CLI, create an inbox, and add the openmail skill so Claude Code can send, read, and reply. - [CLI](https://docs.openmail.sh/integrations/cli.md): Every openmail command with a runnable example, for agents that work from a shell. - [Agent frameworks](https://docs.openmail.sh/integrations/agent-frameworks.md): Integrate OpenMail with LangChain, Vercel AI SDK, or any tool-calling framework. Includes examples for inbox creation and inbound email handling. - [Agent keys](https://docs.openmail.sh/best-practices/api-key-scopes.md): Give each agent an inbox-scoped API key so a compromised or prompt-injected agent can reach nothing but its own inbox. Keep the account-wide key on your side. - [Email deliverability](https://docs.openmail.sh/best-practices/email-deliverability.md): How to send so your agents' email lands in the inbox: domain setup, letting the cold cap do the warm-up, and content that gets replies. - [Idempotency](https://docs.openmail.sh/best-practices/idempotency.md): Use idempotency keys to safely retry failed send requests without creating duplicate emails. OpenMail rejects duplicate requests for 24 hours. - [Frequently Asked Questions](https://docs.openmail.sh/pages/resources/faq.md): Frequently asked questions about OpenMail — inboxes, pricing, custom domains, sending limits, authentication, and agent integrations answered. - [Support](https://docs.openmail.sh/pages/resources/support.md): Get help with OpenMail via Discord, email support, or GitHub issues. Find answers to common questions, report bugs, and request new features. - [SPF, DKIM, DMARC](https://docs.openmail.sh/pages/resources/security/email-protocols.md): How OpenMail implements SPF, DKIM, and DMARC to authenticate your emails and maximize inbox delivery rates for outbound agent messages. - [Introduction](https://docs.openmail.sh/api-reference/introduction.md): Complete reference for the OpenMail REST API — create and manage inboxes, custom domains, send messages, read threads, handle attachments, and configure webhooks. - [API Overview](https://docs.openmail.sh/api-reference/overview.md): OpenMail REST API reference overview — base URL, JSON request/response format, HTTP status codes, and standardized error payloads explained. - [Authentication](https://docs.openmail.sh/api-reference/authentication.md): OpenMail uses API key authentication. Pass your secret key as a Bearer token in the Authorization header on every request to the REST API. - [List pods](https://docs.openmail.sh/api-reference/pods/list-pods.md): List all pods for your account. The default pod is always returned first. Supports pagination. - [Create pod](https://docs.openmail.sh/api-reference/pods/create-pod.md): Create a new pod (an isolated sub-account for one of your end users or tenants). Pass your own `clientId` to map the pod to a record in your system and address it later without storing the OpenMail ID. - [Get pod](https://docs.openmail.sh/api-reference/pods/get-pod.md): Retrieve a single pod by its OpenMail ID or your own `clientId`. - [Update pod](https://docs.openmail.sh/api-reference/pods/update-pod.md): Update a pod's `clientId` or `name`. Only the fields you include are changed. - [Delete pod](https://docs.openmail.sh/api-reference/pods/delete-pod.md): Permanently delete a pod. The pod must be empty (no inboxes or pod-scoped domains) and cannot be the default pod. - [Create pod API key](https://docs.openmail.sh/api-reference/pods/create-pod-api-key.md): Mint an API key scoped to this pod. The key can read and send from the pod's inboxes, create and delete inboxes in this pod, mint/revoke inbox keys for those inboxes, and manage pod/inbox policy and pod-scoped domains. It cannot change webhook config, manage pods, mint further pod keys, reach anothe… - [List pod API keys](https://docs.openmail.sh/api-reference/pods/list-pod-api-keys.md): List the (non-revoked) API keys scoped to this pod. Only non-secret fields are returned — the token itself is never retrievable after creation. - [Revoke pod API key](https://docs.openmail.sh/api-reference/pods/revoke-pod-api-key.md): Permanently revoke a pod-scoped API key. Any integration using it immediately starts getting 401s. Requires an account-wide key. - [List inboxes](https://docs.openmail.sh/api-reference/inboxes/list-inboxes.md): List all inboxes for your account. Supports pagination. - [Create inbox](https://docs.openmail.sh/api-reference/inboxes/create-inbox.md): Create a new email inbox. Optionally set a sender display name. - [Get inbox](https://docs.openmail.sh/api-reference/inboxes/get-inbox.md): Retrieve a single inbox by its ID, including its address, display name, and creation time. - [Delete inbox](https://docs.openmail.sh/api-reference/inboxes/delete-inbox.md): Permanently delete an inbox and stop delivery to its address. This action cannot be undone. An account-wide key or a pod-scoped key for this inbox's pod may delete it; an inbox-scoped key cannot. - [Create inbox API key](https://docs.openmail.sh/api-reference/inboxes/create-inbox-api-key.md): Mint an API key scoped to this inbox. The key can only read and send from this one inbox — its threads, messages, and drafts — and can never reach another inbox, manage pods, or mint keys. The full `token` is returned once, here — store it securely, it cannot be retrieved again. An account-wide key,… - [List inbox API keys](https://docs.openmail.sh/api-reference/inboxes/list-inbox-api-keys.md): List the (non-revoked) API keys scoped to this inbox. Only non-secret fields are returned — the token itself is never retrievable after creation. An account-wide key, or a pod-scoped key for this inbox's pod, may list; an inbox-scoped key cannot. - [Revoke inbox API key](https://docs.openmail.sh/api-reference/inboxes/revoke-inbox-api-key.md): Permanently revoke an inbox-scoped API key. Any integration using it immediately starts getting 401s. An account-wide key, or a pod-scoped key for this inbox's pod, may revoke; an inbox-scoped key cannot. - [List custom domains](https://docs.openmail.sh/api-reference/domains/list-custom-domains.md): List the custom domains on your account. A pod-scoped key sees only its pod's domains plus account-wide ones. - [Add custom domain](https://docs.openmail.sh/api-reference/domains/add-custom-domain.md): Add a custom domain to your account. The response includes the DNS records to publish (`records`). Once you publish them, the domain verifies automatically within a couple of minutes — poll `GET /v1/domains/{id}` until `status` is `verified`, then create inboxes on it. A pod-scoped API key creates t… - [Get custom domain](https://docs.openmail.sh/api-reference/domains/get-custom-domain.md): Retrieve a single custom domain by its ID, including its verification `status` and the DNS records to publish. Poll this after adding a domain to watch it flip to `verified`. - [Change custom domain pod scope](https://docs.openmail.sh/api-reference/domains/change-custom-domain-pod-scope.md): Change which pods can create inboxes on a custom domain. Pass `podId: null` to make it account-wide (always allowed), or a pod id to scope it to that pod — allowed only while every inbox on the domain already lives in that pod, since inboxes cannot move between pods. DNS records and verification are… - [Re-check custom domain](https://docs.openmail.sh/api-reference/domains/re-check-custom-domain.md): Force an immediate DNS re-check of a custom domain, instead of waiting for the automatic background check. The domain verifies on its own within a couple of minutes of you publishing the records, so this is only needed to speed that up. An account-wide key may re-check any domain; a pod-scoped key m… - [Delete custom domain](https://docs.openmail.sh/api-reference/domains/delete-custom-domain.md): Remove a custom domain from your account. The domain must have no inboxes — delete those first. This does not remove the DNS records from your registrar. An account-wide key may delete any domain; a pod-scoped key may delete only a domain scoped to its own pod, never an account-wide domain. Inbox-sc… - [Send email](https://docs.openmail.sh/api-reference/messages/send-email.md): Send an email from an inbox. Optionally pass an Idempotency-Key header to make retries safe: a repeat with the same key within 24 hours returns the original message instead of sending again. Without it the API generates a key and sends once. Use threadId to reply to an existing thread. When replying… - [List messages](https://docs.openmail.sh/api-reference/messages/list-messages.md): List all messages in an inbox, across every thread. Supports pagination for high-volume inboxes. - [List threads](https://docs.openmail.sh/api-reference/threads/list-threads.md): List threads for an inbox. Use isRead to filter by read status — for example, ?isRead=false returns only unread threads. (snake_case is_read is accepted as an alias.) - [Update thread](https://docs.openmail.sh/api-reference/threads/update-thread.md): Update a thread's read status. Use this to mark a thread as read after your agent has processed it, or as unread to re-queue it for later processing. - [Get thread messages](https://docs.openmail.sh/api-reference/threads/get-thread-messages.md): Retrieve a thread and all of its messages in order, with read status and full message content. - [Download raw message](https://docs.openmail.sh/api-reference/messages/download-raw-message.md): Returns the original RFC 822 bytes of an inbound message as `message/rfc822`, exactly as received. - [Get correspondent policy](https://docs.openmail.sh/api-reference/policy/get-correspondent-policy.md): Read the correspondent policy for a scope (account by default, or a pod/inbox). Returns the mode this scope sets for each direction, the effective mode after inheritance, this scope's own rules, and the rules inherited from parent scopes. Inbox-scoped keys are rejected. A pod-scoped key may read its… - [Replace correspondent policy](https://docs.openmail.sh/api-reference/policy/replace-correspondent-policy.md): Declaratively set a scope's entire policy in one call — ideal for automated provisioning. Sets the inbound and/or outbound mode and REPLACES the scope's own rules for any direction you include. Rules created here are fail-closed (an empty allowlist denies all). Omitted directions are left untouched.… - [Set correspondent policy mode](https://docs.openmail.sh/api-reference/policy/set-correspondent-policy-mode.md): Set the filtering mode for one direction of a scope's policy, without touching rules. Inbox-scoped keys are rejected. A pod-scoped key may mutate its own pod or an inbox in that pod, never account-wide policy. Pod keys cannot set `none`. - [Add correspondent policy rule](https://docs.openmail.sh/api-reference/policy/add-correspondent-policy-rule.md): Add one allow/block rule for a direction of a scope's policy. Inbox-scoped keys are rejected. A pod-scoped key may mutate its own pod or an inbox in that pod, never account-wide policy. Pod keys cannot add allows on a parent allowlist (blocks are fine). - [Delete correspondent policy rule](https://docs.openmail.sh/api-reference/policy/delete-correspondent-policy-rule.md): Remove a single policy rule by its ID. Inbox-scoped keys are rejected. A pod-scoped key may delete a rule on its own pod or an inbox in that pod, never an account-wide rule. - [List correspondent policy audit events](https://docs.openmail.sh/api-reference/policy/list-correspondent-policy-audit-events.md): Read the append-only audit trail for correspondent policy, newest first. Two kinds of event share one stream: `rule_added`, `rule_removed`, `mode_changed`, and `scope_deleted` record who moved the boundary and how (`scope_deleted` covers a pod or inbox being deleted, which cascade-deletes its policy… - [Download attachment](https://docs.openmail.sh/api-reference/attachments/download-attachment.md): Returns the attachment bytes. Authenticate with `Authorization: Bearer `. The response is the file itself (not a redirect), so clients can fetch the URL from `attachments[].url` with the same API key they use for the rest of the API. - [Get cold outreach limits](https://docs.openmail.sh/api-reference/limits/get-cold-outreach-limits.md): Today's caps on emailing **new recipients** — people who have never written to the inbox — and how much of each you have used. Returns the account cap, every verified custom domain's warm-up tier and what unlocks the next one, and a `nextStep` sentence you can act on. Replies and follow-ups never co… - [List owned domains](https://docs.openmail.sh/api-reference/owned-domains/list-owned-domains.md): List the domains your organisation has registered for ownership proof, verified or not. - [Add owned domain](https://docs.openmail.sh/api-reference/owned-domains/add-owned-domain.md): Register a domain your organisation controls but does not send from through OpenMail — your company's main domain, say, while your agents send from a subdomain. Once verified, recipients on it (and on any subdomain) do not count as new recipients for the cold outreach limits, so agents can write to… - [Get owned domain](https://docs.openmail.sh/api-reference/owned-domains/get-owned-domain.md): Fetch one owned domain, including the TXT record to publish and its current status. - [Verify owned domain](https://docs.openmail.sh/api-reference/owned-domains/verify-owned-domain.md): Look up the TXT record now and update `status`. Call this after publishing the record. A resolver failure leaves the status unchanged rather than marking the domain failed. - [Delete owned domain](https://docs.openmail.sh/api-reference/owned-domains/delete-owned-domain.md): Remove an owned domain. Recipients on it count as new recipients again from the next send. This does not remove the TXT record from your DNS. - [Report feedback](https://docs.openmail.sh/api-reference/feedback/report-feedback.md): Report a bug, a point of friction, or a feature request directly to the OpenMail team. If an API call fails unexpectedly, a response looks wrong, or you notice something that would make OpenMail work better for you, send it here — one call, no confirmation needed, and the team reads every report. Wo… ## OpenAPI Specs - [openapi](https://api.openmail.sh/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.