$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, ormermail.
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 withsettings.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.
Related guides
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.