{receiver}

Quick Start

Create a project and an API key, then receive your first email from a test suite or from an AI agent. About five minutes either way.

1. Sign Up

Go to receiver.email/login and enter your email address. You'll receive a 6-digit code; enter it to create your account. No password needed.

2. Create a Project

Click Create Project and give it a name, such as "Signup tests" or "Support agent". The project gets an address suffix:

[email protected]

Every address ending in that suffix is an inbox of the project, so [email protected] works with no setup. Use one project per test suite or per agent.

3. Create an API Key

In the project's Settings, click Create API Key and copy the key. It starts with recv_live_, belongs to this project, and is only shown once. Store it as an environment variable:

bash
export RECEIVER_API_KEY="recv_live_your_key_here"

Check it works by sending yourself a test email with the CLI:

bash
npx @receiverdotemail/cli whoami
ADDRESS=$(npx @receiverdotemail/cli inbox new)
npx @receiverdotemail/cli test-email "$ADDRESS"
npx @receiverdotemail/cli otp "$ADDRESS"   # prints the 6-digit test code

Now pick your path.

4a. For a Test Suite

Install an SDK:

TypeScript

bash
npm install @receiverdotemail/sdk

Python

bash
pip install receiverdotemail

In each test, mint an address, have your app send to it, and wait from the address's createdAt:

TypeScript
import { ReceiverClient } from "@receiverdotemail/sdk";

const receiver = new ReceiverClient(); // reads RECEIVER_API_KEY

test("sign-up sends a working code", async () => {
  const inbox = await receiver.inboxes.create({ prefix: "signup" });
  await app.signUp(inbox.address);

  const otp = await receiver.emails.waitForOtp({
    recipient: inbox.address,
    since: inbox.createdAt,
    timeout: 60,
  });
  await app.verify(otp.code);
});

Or in Python:

Python
from receiverdotemail import ReceiverClient

async def test_sign_up_sends_a_working_code(app):
    async with ReceiverClient() as receiver:  # reads RECEIVER_API_KEY
        inbox = await receiver.inboxes.create(prefix="signup")
        await app.sign_up(inbox.address)

        otp = await receiver.emails.wait_for_otp(
            recipient=inbox.address,
            since=inbox.created_at,
            timeout=60,
        )
        await app.verify(otp.code)

For links instead of codes, use waitFor() and read email.links. If nothing arrives in time, both throw ReceiverTimeoutError and the test fails with a clear message.

4b. For an AI Agent

Add the MCP server to your agent. In Claude Code:

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

Other clients (Claude Desktop, Cursor, VS Code, Windsurf) are on the MCP Server page. Then ask for a task that needs email:

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 calls create_inbox, types the address into the form, calls wait_for_email and gets the code back as JSON.

Next Steps