Give your agent an inbox

Let an AI agent create its own email address, wait for a message and read the code or link, so it can finish sign-ups and verifications without a human.

What your agent gets

The MCP server gives the agent four tools. Most tasks use two of them:

1. create_inbox: returns a fresh address under your project and a since timestamp.
2. The agent uses the address, for example in a sign-up form.
3. wait_for_email: waits for mail to that address received after since and returns it, with the code pulled out when you ask for extract: "otp".

list_emails and get_email cover the rest: looking back at what arrived and reading a full message with its links and attachments.

1. Create a project and an API key

Sign up, create a project for the agent and create an API key in the project's settings. A key starts with recv_live_ and belongs to that one project.

Use one project per agent or deployment. The project is the isolation boundary, so two agents with their own projects never see each other's mail.

2. Add the MCP server

In Claude Code:

claude mcp add receiver \
  -e RECEIVER_API_KEY=recv_live_your_key \
  -- npx -y @receiverdotemail/mcp

Any other MCP client takes the same command in its JSON config. The MCP server page has the file for Claude Desktop, Cursor, VS Code and Windsurf.

{
  "mcpServers": {
    "receiver": {
      "command": "npx",
      "args": ["-y", "@receiverdotemail/mcp"],
      "env": { "RECEIVER_API_KEY": "recv_live_your_key" }
    }
  }
}

3. Ask for the task

The tool descriptions tell the model when to use each tool, so a plain request works. Naming the tools makes it reliable:

Sign up for an account at https://acme.example/signup.
Use create_inbox for the email address, then wait_for_email
with extract "otp" to get the verification code and enter it.

The agent's tool calls look like this:

// create_inbox
{ "prefix": "acme" }
// result
{ "address": "[email protected]",
  "since": "2026-11-05T10:00:00.000Z" }

// wait_for_email
{ "address": "[email protected]",
  "since": "2026-11-05T10:00:00.000Z",
  "extract": "otp" }
// result
{ "status": "received",
  "email": { "id": "email_xyz", "from": "[email protected]",
             "subject": "Your Acme code", "receivedAt": "2026-11-05T10:00:04.120Z",
             "text": "Your verification code is 847291..." },
  "otp": { "code": "847291", "candidates": ["847291"] } }

When the email is slow

wait_for_email waits up to timeoutSeconds (60 by default, 300 at most). If nothing arrives it returns a result, not an error:

{ "status": "timeout",
  "since": "2026-11-05T10:00:00.000Z",
  "hint": "No email yet. Call wait_for_email again with the same since." }

The agent calls it again with the same since, so an email that lands between the two calls still counts. If it keeps timing out, the site probably never sent the email: have the agent check the page for an error or a resend button.

Without MCP

Agents that run shell commands can use the CLI. receiver otp prints only the code and exits with 2 on timeout:

export RECEIVER_API_KEY=recv_live_your_key
ADDRESS=$(receiver inbox new --prefix acme)
# ...sign up with $ADDRESS...
CODE=$(receiver otp "$ADDRESS" --timeout 120)

If you write the agent's tools yourself, wrap the TypeScript or Python SDK:

import { ReceiverClient, ReceiverTimeoutError } from "@receiverdotemail/sdk";

const receiver = new ReceiverClient({ apiKey: process.env.RECEIVER_API_KEY });

export async function createInbox() {
  const inbox = await receiver.inboxes.create({ prefix: "agent" });
  return { address: inbox.address, since: inbox.createdAt };
}

export async function waitForCode(address: string, since: string) {
  try {
    const otp = await receiver.emails.waitForOtp({ recipient: address, since, timeout: 120 });
    return { code: otp.code };
  } catch (err) {
    if (err instanceof ReceiverTimeoutError) return { status: "timeout", since };
    throw err;
  }
}

Keeping it safe

• Scoped keys: an API key reads its own project's mail and mints addresses. It cannot create keys, manage webhooks or delete the project, so a leaked agent key cannot widen its own access.
• Receive only: addresses receive mail and never send it.
• Retention: mail is deleted after your plan's retention period. Agents can also delete a message once they have used it.
• Terms of service: only automate sign-ups on services that allow it, such as your own product or tools you are licensed to use.

Next Steps

• MCP Server: every tool, its inputs and its output
• CLI: commands, JSON output and exit codes
• Concepts: projects, inboxes, keys and since