Explore
Provisional mailbox
A random address is created idempotently for the local client. It expires, cannot send, and gives the agent enough access to receive a verification email or inspect an inbox.
Agent mailbox feature
A mailbox identity that belongs to the agent, not a human.
Create a receive-only temporary inbox for the first task, then promote the workflow to a permanent named mailbox only when a human approves the identity.
Direct answer
mails0 provides two mailbox lifecycles: a random 72-hour provisional mailbox that the official CLI or MCP server can create automatically, and a permanent mailbox that requires an explicit claim. Both use scoped credentials, so an agent does not need access to a personal Gmail or Outlook account.
Decision map
Temporary first, permanent only after value
- 01Provisional mailbox
A random address is created idempotently for the local client. It expires, cannot send, and gives the agent enough access to receive a verification email or inspect an inbox.
- 02Permanent mailbox
A human chooses the name and approves the claim. The resulting mailbox-scoped key supports the capabilities allowed by the hosted or self-hosted deployment.
- 03Self-hosted mailbox
Teams can deploy the API under their own Cloudflare account and domain, then define retention, sender configuration, quotas, and operational controls themselves.
Identity lifecycle
Temporary first, permanent only after value
Mailbox creation is a security decision and a product-conversion decision. The lifecycle should match the uncertainty of the workflow.
Commit
Permanent mailbox
A human chooses the name and approves the claim. The resulting mailbox-scoped key supports the capabilities allowed by the hosted or self-hosted deployment.
Own
Self-hosted mailbox
Teams can deploy the API under their own Cloudflare account and domain, then define retention, sender configuration, quotas, and operational controls themselves.
First-value workflow
How an agent receives its first real message
-
01
Bootstrap locally
Run
mails bootstrapor call an MCP inbox tool. The client stores the scoped key locally instead of returning it to the model transcript. -
02
Use the generated address
Enter the address into the signup, notification, or verification flow that the agent is already operating.
-
03
Wait for the inbound message
Poll through the CLI, API, Python SDK, or MCP server. Filter for inbound mail or use the code-specific wait operation.
-
04
Keep or discard the identity
If the workflow produced value, claim a permanent name with human approval or deploy your own domain. Otherwise let the provisional mailbox expire.
Automatic temporary inbox
npm install -g mails-agent
mails bootstrap
mails inbox --direction inbound --limit 1Security boundary
Why a dedicated agent mailbox is safer than a human inbox
Human mailbox OAuth often exposes years of unrelated messages, contacts, password resets, and business correspondence. A dedicated agent mailbox starts empty and can be limited to one application, test suite, or automation role.
A mailbox-scoped credential also makes revocation understandable. Operators can pause one identity without disabling every agent or rotating a broad account-wide secret. Provisional credentials narrow the first-run risk further by removing outbound sending and enforcing expiry.
- Use one mailbox per trust boundary, not one shared inbox for every agent.
- Keep credentials in the client or secret store; do not paste them into prompts or logs.
- Treat permanent claims and outbound sending as operator-approved capabilities.
- Use self-hosting when domain, retention, data residency, or reputation ownership is required.
Choose the right state
Mailbox lifecycle decision table
| Situation | Recommended mailbox | Reason |
|---|---|---|
| One signup or OTP task | Provisional hosted mailbox | Fastest bounded proof with automatic expiry and no sending. |
| Recurring coding-agent notifications | Permanent mailbox | Stable address and scoped identity for an ongoing tool. |
| CI run isolation | New provisional mailbox per test boundary | Prevents stale messages from contaminating assertions. |
| Production customer workflow | Self-hosted mailbox on your domain | You control domain, retention, quotas, and operations. |
| Access to an employee inbox | Use the provider API with explicit OAuth review | mails0 should not impersonate an existing human mailbox. |
Evidence
Sources and product scope
Product behavior is verified against the mails0 source and documentation. External comparisons link to official vendor documentation checked on 2026-08-15.
- mails0 source repositoryImplementation, license, and deployment source
- mails0 mailbox documentationHosted and self-hosted mailbox lifecycle
Questions and answers
Questions about Agent mailboxes
Can an agent create a mailbox without a human filling out a form?
Yes. The official CLI and MCP server can bootstrap a random provisional mailbox automatically. The hosted provisional mailbox is receive-only, expires after 72 hours, and is subject to abuse limits.
Can an agent automatically claim a permanent mails0.com address?
No. Permanent hosted claims require explicit human approval. This keeps durable identities and outbound capability behind a deliberate control while preserving automatic first-run discovery.
Where is the mailbox API key stored?
The CLI and MCP packages store the scoped key in local client state. The bootstrap response is designed so the key does not need to be exposed in a model conversation.
Can I use my own domain for agent mailboxes?
Yes. Self-host mails0 on Cloudflare and configure Email Routing and your outbound sender for a domain you control.
Start with a bounded inbox
Give the agent an inbox, then prove the workflow.
Start with a receive-only temporary mailbox. Move to a permanent identity or self-hosted deployment only after the workflow reaches a real email value event.