Create a mailbox

Create a mailbox when an agent needs its own email identity. 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. Pass an Idempotency-Key when you may repeat the same create attempt. If the result is uncertain, list mailboxes and resolve the exact normalized address before deciding whether to retry.

Create a hosted mailbox

Open the workspace

In the console, select the workspace that should own the mailbox.

Start mailbox creation

Click New mailbox.

Choose a hosted address

Enter a valid username for the mermail.app domain.

Create the mailbox

Confirm the address and create the mailbox.

Create a custom-domain mailbox

First, connect a custom domain to the workspace and wait until it shows Sending ready and Receiving ready. Once the domain is ready, every mailbox in the workspace moves to it automatically and keeps its username. New mailboxes are created on the custom domain.

Open the workspace

In the console, select the workspace that owns the connected domain.

Start mailbox creation

Click New mailbox. The address uses the workspace’s custom domain.

Choose the address

Enter the username that should appear before @.

Confirm the mailbox

Review the complete custom-domain address and create the mailbox.

Custom domains require a paid plan, such as Developer. Each workspace supports one custom domain.

Receive mail from an existing inbox

You can keep using Gmail, Outlook, or another email provider and forward selected messages to the new Mermail mailbox. Mermail does not receive direct access to the provider account.

Set up auto forwarding

Define a privacy-first forwarding rule and choose a provider guide.

Create a verification-only agent inbox

Discover existing mailboxes first. Reuse one only when it is enabled, can receive mail, and is dedicated to the same service, task, person, and third-party account. The CLI can perform one exact discover-or-provision pass:

mermail mailboxes ensure \
  --email [email protected] \
  --name "Agent task inbox" \
  --verification-mode \
  --idempotency-key agent-task-4f2a

--verification-mode stores:

{
  "agentInbox": {
    "mode": "verification",
    "automationsEnabled": false
  }
}

This avoids running the default auto-draft workflow for verification mail. Verification mode also implicitly requires a clean scan before model-backed inbound classification or automation can run. A skipped or unavailable scan keeps the delivered message but suppresses that model-backed work. Standard mailboxes can opt into the same gate with settings.agentInbox.requireCleanScanForAutomation: true; existing mailbox behavior remains unchanged when the setting is omitted. With --verification-mode, mailboxes ensure reuses the exact address only when its settings explicitly contain agentInbox.mode: "verification" and agentInbox.automationsEnabled: false. If a usable standard mailbox already owns that address, ensure returns HTTP-style status 409 with mailbox_ensure_purpose_mismatch. It does not silently reuse or reconfigure the mailbox. Choose a task-specific alias, or manage the existing mailbox settings explicitly before running ensure again. With the HTTP API or MCP, email and name are required. workspaceId is optional when the API key or OAuth grant already binds the request to one workspace. If supplied, it must match the credential scope. If a provisioning response is lost or returns 409, list mailboxes and resolve the exact normalized address before considering another create. Never blind-retry a paid provisioning write. mailboxes ensure derives a purpose/workspace/address-scoped idempotency key when you omit the explicit flag.

Troubleshooting

Problem	What to check
Username is rejected	Check length, separators, characters, and reserved terms
Custom domain is rejected	Use a domain without existing email (MX) records, such as a dedicated subdomain like `mail.example.com`
Domain cannot be verified	Click Check connection on the Custom Domains page and follow the message shown for each record
Mailbox limit reached	Check the workspace plan limits
`welcome_onboarding_status` remains `pending`	This is the welcome/demo-message status, not inbound readiness; check `can_receive` and `receiving_status`
A custom-domain mailbox can send but cannot receive	Re-check the domain’s current Receiving MX records; send verification alone is not enough for `can_receive: true`
The exact address already exists	Reuse it only when `receiving_status` is `ready` and its purpose matches the requested workflow; `--verification-mode` otherwise returns `mailbox_ensure_purpose_mismatch`
A create response is uncertain	List and resolve the exact address before retrying

Email module

Review hosted vs custom-domain send, receive, and attachment limits.

Get started

Core concepts

Guides

Usecases

Integrations

Security and data

Legal

Resources

Create a mailbox

Create a hosted mailbox

Create a custom-domain mailbox

Receive mail from an existing inbox

Set up auto forwarding

Create a verification-only agent inbox

Troubleshooting

Email module

​Create a hosted mailbox

​Create a custom-domain mailbox

​Receive mail from an existing inbox

Set up auto forwarding

​Create a verification-only agent inbox

​Troubleshooting

Email module

Create a hosted mailbox

Create a custom-domain mailbox

Receive mail from an existing inbox

Create a verification-only agent inbox

Troubleshooting