How to give an AI agent an email address
Start with an automatically generated receive-only mailbox, prove one inbound task, then decide whether the agent needs a permanent name or self-hosted domain.
Install mails-agent, run mails bootstrap, and give the returned address to the workflow that needs email. The CLI stores the mailbox-scoped key locally. Use mails inbox or mails code to retrieve the first message. Claim a permanent name only with human approval, or self-host mails0 when the agent needs your domain and owned infrastructure.
Workflow at a glance
Create and inspect the first mailbox
- 01Install the CLI
Install the
mails-agentpackage globally so themailscommand is available to the local agent runtime. - 02Bootstrap the mailbox
Run
mails bootstrap. The hosted service creates an idempotent provisional mailbox and the client stores its key locally. - 03Confirm identity
Run
mails meto inspect the current mailbox, scope, expiry, and capabilities without printing the secret. - 04Receive the first email
Use the address in the external flow, then call
mails inboxormails codewith a deadline.
Define the email job and the trust boundary
Write down why the agent needs email, who is expected to send the first message, whether the identity should survive the current task, and whether outbound sending is required. This determines whether a temporary hosted mailbox is enough.
Do not begin by connecting a personal mailbox. A new dedicated identity is usually the safer path for signup, verification, testing, or project notifications because it starts with no unrelated history.
- Expected sender or service.
- Expected result: code, link, status, message, or reply.
- Maximum wait time and failure behavior.
- Retention, cleanup, and whether a permanent name is justified.
Create and inspect the first mailbox
-
01
Install the CLI
Install the
mails-agentpackage globally so themailscommand is available to the local agent runtime. -
02
Bootstrap the mailbox
Run
mails bootstrap. The hosted service creates an idempotent provisional mailbox and the client stores its key locally. -
03
Confirm identity
Run
mails meto inspect the current mailbox, scope, expiry, and capabilities without printing the secret. -
04
Receive the first email
Use the address in the external flow, then call
mails inboxormails codewith a deadline.
npm install -g mails-agent
mails bootstrap
mails me
mails inbox --direction inbound --limit 5Let an MCP client acquire the same bounded identity
Configure mails-agent-mcp in the client and call an inbox-oriented tool. When no key exists, the server can bootstrap a provisional mailbox automatically and store the credential outside the model transcript.
MCP is useful when the agent must choose among inbox, code, search, message, and thread operations during an interactive task. Deterministic tests may be simpler through the CLI, HTTP API, or SDK.
npx -y [email protected]Do not ask for permanence before the first email value event
| Observed state | What it proves | Next action |
|---|---|---|
| Mailbox created | Identity provisioning works. | Use the address in the real workflow. |
| Inbox read | Credential and retrieval work. | Trigger and wait for an external message. |
| First message received | Routing and storage work. | Extract the required value and finish the task. |
| Code or link succeeds | The email workflow produced value. | Consider a permanent mailbox if the task recurs. |
| Recurring authorized use | Durable identity has a reason to exist. | Claim with approval or self-host on your domain. |
Move to a permanent or self-hosted mailbox deliberately
A permanent hosted mailbox is appropriate for a recurring low-volume identity that fits the hosted service controls. A self-hosted mailbox is appropriate when your organization needs its own domain, data location, quotas, retention, sender provider, or operational policy.
Neither transition should be automatic merely because installation succeeded. First prove the external message and final user or agent outcome, then choose the durable operating model.
Define success before the agent creates the address
Write the smallest observable outcome first: receive one verification message, extract one value, and prove the external account reached the intended state. Record the recipient and trigger time so stale mail cannot satisfy the run. If that bounded loop fails, improve retrieval or workflow logic before granting a permanent identity. If it succeeds repeatedly, name an owner, choose retention, review provider terms, and decide whether the address should be claimed or moved to a self-hosted domain. This staged decision keeps conversion tied to completed work instead of vanity mailbox counts and prevents provisional credentials from quietly becoming production infrastructure.
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 quickstartCLI and API setup
- mails0 mailbox lifecycleTemporary and permanent mailbox behavior
Questions that come up in practice
Can the agent create the temporary inbox itself?
Yes. The official CLI and MCP packages can bootstrap a provisional hosted mailbox automatically within abuse and capacity controls.
Does a temporary mailbox support sending?
No. The hosted provisional scope is receive-only. Sending requires an eligible permanent or self-hosted mailbox.
How long does the temporary mailbox last?
The current hosted provisional configuration expires after 72 hours. Self-hosted operators can configure their own lifecycle.
When should I claim a permanent address?
After a real inbound workflow succeeds and the agent has a recurring need for the same identity, with a human approving the durable name and capability.
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.