Test inbox
A test inbox is a mailbox on a generated, non-routable .mail.invalid address with a simulated transport, producing real events, approvals and error codes while being unable to reach any internet recipient.
You can unit-test an agent’s reasoning. You cannot unit-test what happens when a real message lands in a real inbox, a model decides what to do with it, and a real recipient gets the result. A test inbox is the environment in between, where everything is real except the delivery.
Why the address cannot resolve
A test inbox is issued on a generated address ending in .mail.invalid. The
.invalid top-level domain is reserved by RFC 6761 precisely so that it can never
resolve, which makes this a stronger guarantee than a flag that suppresses sending.
There is nowhere for the mail to go. If every guard in the application failed at
once, DNS still has no answer.
The environment is fixed at the project, not at the message. A project carries an
environment of test or live, chosen at creation, and attempting to change it
returns environment_immutable. There is no promotion path, so you keep two projects
and swap credentials, and the credential itself cannot cross: an efa_test_ key
resolves only to test projects and test inboxes.
You also cannot customise a test address. Passing local_part or domain_id to a
test project returns HTTP 422 test_mode_unsupported, and test projects cannot
attach custom domains at all.
The caps, which are enforced in code
| Limit | Value | Error when exceeded |
|---|---|---|
| Active test inboxes per workspace | 3 | HTTP 403 test_limit_exceeded |
| Retained test messages | 100 | HTTP 403 test_limit_exceeded |
| Retained test content | 10 MiB | HTTP 403 test_limit_exceeded |
| Test content expiry | 7 days | content ages out |
Three inboxes is enough for one agent under test, one for the counterparty role, and one spare. Test mail is never counted as an email unit, so a suite that runs the whole receive-and-reply loop on every commit costs nothing.
What is real inside it
Everything except the transport. Inbound mail is injected through the project’s test
endpoint and produces genuine message.received events on the same event stream your
production code reads. Approvals are real approvals with real reason codes. Policy
denials return the same policy_denied and recipient_not_allowed errors as live
mail. Webhooks are real signed webhooks, which means your signature verification code
is exercised by the same implementation that will verify production callbacks.
That is the point of the arrangement: the three things that break in the first week of an agent email integration are all integration bugs rather than model bugs. The agent replies to an address lifted out of quoted text. Retry logic mints a fresh idempotency key per HTTP attempt, so one timeout becomes two emails. A webhook handler acts twice on a redelivered event. None of the three needs a real recipient to reproduce, and all three are covered in testing an agent’s email without sending real mail.
What it cannot tell you
Anything about deliverability. A simulated transport has no SPF, no DKIM alignment, no reputation, no greylisting and no spam filter, so a message that works perfectly here can still be filtered in production. Nothing observed in a test inbox is evidence about inbox placement.
Anything about a real recipient’s client. Rendering, threading behaviour in a specific mail app, and how a human reads a message are outside the boundary.
It is also worth being precise about what is distinctive here, because inbound testing is not rare. Several email testing products provision a routable hosted address and serve parsed inbound mail over an API, and at least one documents originating a message itself to simulate a sender. The narrower difference is whose mailbox the message lands in and whether it crosses a transport at all: this is a non-routable address in the agent’s own inbox, with messages injected directly, rather than a real transmission into a stand-in mailbox. Which of those you want depends on whether you are testing the agent or testing your MTA configuration. The CI-shaped version of the first is in running an inbound email loop in CI.