Concepts

Projects, inboxes, API keys and since: the four ideas every Receiver.email client is built on.

In One Paragraph

A project owns mail and API keys. An inbox is any address under the project's suffix. An API key can mint inboxes and read the project's mail. Waiting for mail always means "the first email received strictly after since". The REST API, SDKs, MCP server and CLI all follow these rules, so the same call gives the same answer from each.

Organizations

An organization is the top-level entity. It represents your company or team and is the unit of billing. When you first sign up, a default organization is created for you automatically.

Projects

A project belongs to an organization and is the isolation boundary: its mail, addresses and API keys are its own. Use one per test suite, per agent or per team.

Inboxes

An inbox is any address under a project: {prefix}{emailSuffix}. Inboxes are unlimited and need no setup, and nothing is stored until mail arrives.

Mint addresses with inboxes.create() in the SDKs, create_inbox in the MCP server, receiver inbox new in the CLI or POST /projects/:id/inboxes. It adds a random suffix so parallel callers never collide, and returns createdAt, the time to wait from. Building an address by hand works too: take the project's emailSuffix and put any prefix in front, never hard-code the domain part.

Emails

An email represents a captured inbound message. When an email arrives, Receiver.email parses it and stores:

Emails are indexed in under 2 seconds and available via the API immediately. They are retained for the duration specified by your plan (7 to 365 days) and then automatically deleted.

API Keys

API keys start with recv_live_ and belong to one project. They are separate from your dashboard login, and the key alone is enough: clients find its project with GET /whoami.

• Create one key per pipeline or agent, so you can revoke one without the others.
• Keys can have an optional expiration date.
• Revoked keys stop working immediately.

Since

since is an ISO 8601 timestamp. A wait (waitFor, waitForOtp, wait_for_email, receiver wait) matches only mail whose receivedAt is strictly after it.

• First email on a new address: use the inbox's createdAt. Nothing from before the address existed can match.
• The next email (after "Resend code", or the second step of a flow): use the receivedAt of the email you already have.
• Omitted: the last 60 seconds, so an email that arrived just before the call still counts.

A wait that times out is a normal result (status: "timeout" in the API, ReceiverTimeoutError in the SDKs, exit code 2 in the CLI). Waiting again with the same since never misses an email that arrived in between.

Email Lifecycle

1. Your application sends an email to one of your project's addresses.
2. The email is received and stored as raw data within milliseconds.
3. An async worker parses the email: extracts metadata, body, links, and attachments.
4. The parsed email is indexed and available via the API (typically under 2 seconds end-to-end).
5. Your test or agent gets it by waiting (long-polling), streaming, a webhook, or listing.
6. After the retention period, the email and its attachments are automatically deleted.

Retention

Each plan has a retention period that determines how long emails are kept:

After the retention window, emails and their attachments are permanently deleted. This is automatic and cannot be undone.

Next Steps

• Quick Start: set up your first project
• Give your agent an inbox: inboxes through MCP
• TypeScript SDK: full SDK reference
• REST API Reference: all endpoints documented