Skip to main content
A mailbox is the email identity your agent uses. It owns messages, folders, drafts, scheduled sends, notification settings, task triagers, and agent conversations. A successful mailbox creation consumes 10 provision credits from the workspace API-credit balance. Provision credits are usage units; they are not a $10 currency charge. For a repeated create attempt, pass an Idempotency-Key with the same intent and re-list the exact normalized address after a conflict or uncertain response. Do not assume that an idempotency key proves exactly-once business execution.

Address types

Mermail recommends a dedicated subdomain such as mail.example.com for custom-domain mailboxes. A domain that already has MX records is not accepted, so your existing company email is not affected. When a workspace connects a custom domain, all of its mailboxes move to that domain. See Custom domains for setup and the Email module for send, receive, attachments, and delivery status.

Hosted mailbox rules

Hosted mailbox usernames:
  • Must be 5 to 30 characters.
  • Can include letters, numbers, dots, underscores, and hyphens.
  • Cannot start or end with a separator.
  • Cannot repeat separators.
  • Cannot include reserved terms such as admin, support, security, or mermail.

Plus aliases

When aliases are available for your hosted mailbox, add a tag to its current address: myagent+receipts@mermail.app. Valid aliases work immediately without creating another mailbox. They share the mailbox’s storage, permissions, sending limits, and billing. Tags contain 1–32 letters, numbers, dots, underscores, or hyphens. Start and end with a letter or number. Tags are normalized to lowercase; additional + separators are not supported. Aliases apply to your current hosted address, not historical addresses or custom-domain addresses. Open Mailbox settings → Aliases to save shortcuts with optional labels, copy an address, view its mail, or create a routine for it. Saving is optional: removing a saved shortcut does not stop delivery. Choose an alias in the compose From field to send from it. Replies default to the verified delivery alias when available. Incoming messages can include delivery_address, the actual delivery address independently of visible To/Cc headers. It is null when verified delivery information is unavailable. An email-received routine can set recipientAlias to a tag such as receipts. It matches the verified delivery alias exactly, in addition to the routine’s other conditions. A message that only mentions an alias in its visible To header does not qualify. Block discards future incoming mail to that alias and stops outgoing sends, including previously scheduled sends. Existing messages and routine settings remain. Unblock restores eligibility. Removing a saved shortcut preserves any existing block. See Use plus aliases for dashboard steps, replying, and blocking.

Alias APIs and MCP

Use the existing mailbox identifier and authentication: Save with { "tag": "receipts", "label": "Receipts" }. Update with { "blocked": true } or { "blocked": false }. Labels may contain up to 80 characters. Reading requires mailbox access; changes require mailbox settings administration permission. MCP updates use the existing confirmation flow because blocking affects delivery. Use the existing email from field to send from an unblocked alias. Do not create another mailbox for each tag. Marketplace inbox restrictions and verification-only automation settings still apply.

Mailbox data

Each mailbox can include:
  • Messages and threads.
  • System folders and user-created folders.
  • Drafts, replies, forwards, and scheduled sends.
  • Attachments.
  • Agent conversations.
  • Telegram and push notification settings.
  • Task triagers for event-driven agent work and inbound draft responses.

Readiness and lifecycle fields

Mailbox API responses can include: welcome_onboarding_status: "pending" does not mean that inbound delivery is pending. Use can_receive and receiving_status for a stable readiness check. For a custom-domain mailbox, these fields are recalculated from the domain’s current receiving-DNS verification state. A domain can be ready to send while its Receiving MX remains pending, in which case the mailbox reports unavailable. When you need end-to-end evidence, also perform a scoped delivery test.

Agent and verification inboxes

Discover existing mailboxes before creating one. Reuse a mailbox only when it belongs to the credential-bound workspace and is clearly dedicated to the same service, task, person, and third-party account. Do not reuse a disabled mailbox or inspect unrelated inboxes to guess. Verification-only inboxes should run with the smallest useful automation and tool surface. Create one with settings.agentInbox: { mode: "verification", automationsEnabled: false } to disable automatic draft/connected-tool work. This setting is additive; existing mailboxes keep their current behavior. The default email-response triager can otherwise hold a new Inbox message temporarily while it prepares a draft; the fail-safe stale window is five minutes. settings.agentInbox.mode accepts standard or verification. settings.agentInbox.automationsEnabled controls whether automatic agent workflows can run. settings.agentInbox.requireCleanScanForAutomation: true suppresses model-backed inbound classification and automation when scanning is skipped or unavailable, while keeping the delivered message. Verification mode enables this clean-scan requirement implicitly. Omitting agentInbox keeps the existing standard behavior.

Email module

Send, receive, custom domains, attachments, and delivery status.

Create a mailbox

Create a hosted mailbox or a mailbox under a verified custom subdomain.