Mailboxes and addresses

A mailbox is a catchall inbox with its own subdomain under mailcatchr.com. When you create a mailbox called acme-ci, its subdomain is acme-ci.mailcatchr.com, and every address on it is delivered:

• alice@acme-ci.mailcatchr.com
• kai+signup-218@acme-ci.mailcatchr.com
• order-8812@acme-ci.mailcatchr.com

Nothing has to be created before a test uses an address. The local part is yours to invent, and the usual pattern is to make it unique per test run so assertions can filter on it:

const address = `signup-${Date.now()}@acme-ci.mailcatchr.com`;

How mail gets there

Your application sends mail the way it does in production, through whatever provider it uses. Because the recipient domain is acme-ci.mailcatchr.com, normal MX delivery brings the message to mailcatchr over SMTP. No configuration in your app changes between environments except the addresses of the test users.

If you would rather bypass your provider, point your app’s SMTP settings at smtp.mailcatchr.com on port 587 (STARTTLS) or 465 (TLS). The server accepts mail addressed to mailcatchr mailboxes and rejects unknown subdomains.

Reading mail

Every message in a mailbox can be read four ways, and they all show the same data:

Way	Best for
Dashboard	Looking at what arrived
REST API and SDKs	Test suites and CI
IMAP or POP3	Testing real mail clients, or tools that speak those protocols
Mail notifications	Reacting to arrival without polling

Retention and limits

Messages are deleted after the mailbox’s retention window, attachments included. The window is 3 days on the Free plan and up to 30 days on Business, set per mailbox. Inbound volume is capped per workspace per day. See Limits and plans.

Creating mailboxes over the API

The Free plan has one mailbox. Business has no limit, and mailboxes can be created programmatically:

curl -X POST -H "Authorization: Bearer $MAILCATCHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"pr-1842"}' \
  "https://api.mailcatchr.com/v1/workspaces/$WORKSPACE_ID/mailboxes/"

The response includes the mailbox id and subdomain. A key scoped to an explicit set of mailboxes cannot see mailboxes created after it was issued; a key scoped to all mailboxes can. See API keys and scopes.