Temp Postal API

The shape of a typical integration

Almost every integration follows the same three steps. Create an inbox and keep the address. Drive your application so it sends mail to that address. Poll the messages endpoint until a message matching an expected subject or token appears, then assert on its contents or extract the link you need to follow.

Because the inbox belongs to a single test, 'the newest message' is unambiguous - there is no filtering against another engineer's run and no stale message from an earlier build. That is what removes the flakiness from email-dependent tests.

Designing for CI without flakiness

Poll on a short interval with a total timeout instead of sleeping for a fixed duration. Fixed sleeps are either too short, which produces intermittent failures, or too long, which multiplies your build time by the number of email tests.

Watch per-minute limits rather than monthly quotas. A suite that creates a hundred inboxes in a single build is bursty by nature, so if you hit a cap, batch inbox creation or reuse one inbox across assertions within a single test rather than across tests.

Treat message bodies as credentials. Verification links and reset tokens are live for the duration of the test, so extract and use them, but keep them out of build logs that anyone with repository access can read.

What the API is not for

It does not send mail. Inboxes are receive-only, so you cannot use it as an outbound relay or to test your own inbound-parsing pipeline by generating traffic from it.

It is not a durable mail store. Retention is short by design; if a test result needs to be archived, capture the parsed values in your test report rather than expecting the message to still exist later.

And it is not a way around third-party signup restrictions. Services that block disposable domains will still block them when the request comes from a script.