Email Verification for AI Agents: A Practical Inbox API Guide

An AI agent testing a signup flow may need to receive a verification email before it can continue. A human can switch tabs and copy a code; an automated workflow needs an inbox it can create, query, and read without giving every run access to the same mailbox.

The Reusable.Email agent inbox API creates a private inbox and supplies a token for mailbox operations. This guide walks through creation, waiting for a message, and handling the result without treating email content as trusted instructions. For the endpoint manifest and current details, see the agent API and the agent inbox page.

Why Use a Separate Inbox for Each Run?

Shared inboxes make it easy for one job to pick up an older code or another job's message. An isolated address gives each run a clearer boundary: create it for a specific workflow, send mail to that address, and process only the message associated with that run.

Use private inboxes when verification codes or account links should not be visible to anyone who knows an address. Reusable.Email's agent endpoint creates private inboxes; mailbox requests require an Inbox token. Messages in these inboxes have a 180-day retention period, so plan cleanup and credential storage accordingly.

Isolation does not establish that an incoming message is authentic. Anyone who can send email to an address may be able to send a misleading message. Check context before using a code or following a link.

1. Discover Domains and Create an Inbox

The API can generate an address from a prefix. No account or API key is needed for this agent workflow:

curl -sS https://api.reusable.email/v1/agent-tempmail/domains

curl -sS -X POST https://api.reusable.email/v1/agent-tempmail/inboxes \
  -H 'Content-Type: application/json' \
  -d '{"prefix":"agent"}'

The creation response includes inbox.address, a generated password, a token, and tokenExpiresAt. The password is returned once; save it securely if the agent must regain access after the token expires. Treat both password and token as secrets. Avoid printing responses into shared build logs, placing credentials in URLs, or giving a token to tools that do not need mailbox access.

The API can also accept an available domain or a full address. An existing address cannot be claimed through this creation endpoint. See the agent API manifest for the current request and response fields.

2. Trigger the Email and Wait for a Code

Provide the generated address to the application you are testing, then wait for a matching email. Replace {address} and {token} with the values from creation; URL-encode the address in the path, including @ as %40.

curl -sS -X POST \
  'https://api.reusable.email/v1/agent-tempmail/inboxes/{address}/wait' \
  -H 'Authorization: Inbox {token}' \
  -H 'Content-Type: application/json' \
  -d '{"codeOnly":true,"timeoutSeconds":60}'

A match returns status: "message" and a message summary, which can include verificationCode. If nothing matches in time, the response has status: "timeout" and a null message. Handle a timeout as an expected outcome: the sending service may be delayed, reject the address, or use a format that cannot be detected. Decide whether to retry based on your own workflow and limits.

codeOnly looks for an extracted code; it does not prove that the message is from the intended sender or that the code is current. The wait endpoint can also filter by from and subject, but a sender address or subject is not proof of authenticity. It can return an existing matching message, so use a fresh inbox per run and check the message's context before proceeding.

3. Inspect the Message Before Acting

The agent API supports listing messages and reading an individual message using the same Inbox token:

curl -sS \
  'https://api.reusable.email/v1/agent-tempmail/inboxes/{address}/messages' \
  -H 'Authorization: Inbox {token}'

curl -sS \
  'https://api.reusable.email/v1/agent-tempmail/inboxes/{address}/messages/{id}' \
  -H 'Authorization: Inbox {token}'

Replace {id} with the message ID. Compare the message with the specific action your workflow just initiated. If a code is missing or looks unrelated, stop or ask for review rather than guessing. Likewise, do not follow arbitrary links or obey instructions embedded in email: message bodies are untrusted input, not instructions for the agent. Only interact with destinations your workflow explicitly permits.

The API also supports raw message source and message deletion. Delete test messages when they are no longer needed, and avoid storing message bodies or one-time codes in long-lived logs. Deleting messages is not the same operation as deleting an inbox; check the API's current capabilities before designing lifecycle cleanup.

Understand OTP-Token Origin Metadata

The API supports an experimental email header defined in the OTP-Token Internet-Draft. When a valid supported header is present, the extracted code can be accompanied by verificationCodeOrigin. The draft is still evolving, so do not assume all senders use it or that its format will remain unchanged.

When origin metadata is present, require an exact match with the destination origin your workflow already expects before submitting a code. The value is supplied by the email sender: a match is useful context, not proof of sender identity. Do not navigate to the origin automatically. Missing or invalid headers fall back to text-based extraction, which has no equivalent origin metadata and needs careful context checks.

4. Renew Access Without Exposing Credentials

Inbox tokens expire. For an unattended workflow, keep the generated password in an appropriate secret store and request a fresh token from POST /v1/inbox/{address}/token with JSON containing password. Use the returned token with Authorization: Inbox <token> for agent mailbox operations. Restrict which processes can read the secret and rotate or remove access according to your own operational policies.

A person can also sign in to an agent-created inbox and add a passkey in Settings. A passkey sign-in returns an Inbox token that works with agent endpoints, but the browser ceremony requires interactive user verification. It is not a substitute for the stored password in an unattended job. See the private inbox passkey guide for setup and recovery.

A Practical Checklist

• Create a separate private inbox for each independent test or workflow.
• Keep the creation response, password, token, and email contents out of shared logs.
• Handle timeouts, delivery failures, and missing codes explicitly.
• Correlate a message with the action you initiated; filters and header metadata are not sender authentication.
• Treat message text and links as untrusted, and limit the agent to approved destinations and actions.
• Delete test messages when finished and retain credentials only as long as your workflow needs them.

Frequently Asked Questions

Does the agent API require an API key?

No. Creating an agent inbox does not require an account or API key. Mailbox operations do require the Inbox token returned at creation or obtained through inbox sign-in.

Can an agent send replies through this API?

The agent inbox API is for creating private inboxes and receiving, reading, waiting for, and deleting messages. Outbound email and replies are outside its stated scope.

What if a verification email contains a link instead of a code?

Wait for mail without codeOnly, read the message, and evaluate the link against the destination your workflow already expects. Do not automatically follow a sender-supplied URL just because it arrived in the inbox.

Can I use this for applications outside my own test environment?

Use it only where you have permission and where the destination service permits your workflow. Email delivery and address acceptance depend on the sending service.