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.

Authentication, errors and retries

Every request carries your key in an `x-api-key` header. A missing or revoked key returns 401, an exhausted monthly allowance returns 402 with an upgrade message, and a burst that exceeds the per-minute limit returns 429 with rate-limit headers telling you the ceiling, what is left and when the window resets. Reading those headers is cheaper than guessing at a backoff.

Retry only on 429 and on 5xx responses, with exponential backoff and jitter so a parallel matrix build does not synchronise its retries into a second burst. Never retry a 4xx that describes your request: a malformed address or an unknown inbox id will fail identically the second time and only slows the suite down.

Treat inbox creation as the one call worth guarding with a retry, because a failure there fails the whole test rather than a single assertion. Message polling already retries by nature, since it loops until the expected message appears or the timeout expires.

Patterns for common test suites

In Playwright or Cypress, create the inbox in a fixture so the address is available to every step, and tear nothing down: retention removes the inbox for you. Pass the address into the signup form, then await a helper that polls the messages endpoint for a subject match and returns the parsed body.

For verification links, extract the first URL matching your own domain rather than the first URL in the body - marketing footers and tracking links appear before the real one often enough to break a naive regex. For numeric codes, match on a fixed digit length anchored to the surrounding copy so a date or an order number cannot be picked up instead.

For load or deliverability probes, create a small pool of inboxes once and reuse them across a run rather than one per message. Thousands of single-use inboxes burn quota with no extra signal, while a fixed pool still tells you whether mail arrives, how fast, and whether authentication passed.

Security and data-handling expectations

Keys belong in your CI secret store, scoped to the pipelines that need them, and rotated from the dashboard whenever someone with access leaves the project. Rotation issues a new key without invalidating a running build immediately, so you can roll forward in one deploy.

Anything an inbox receives should be treated as untrusted input. Parse for the values you expect, do not echo whole bodies into build logs, and never render a fetched HTML body inside your own tooling without sanitising it first.

Because inboxes are public by address, do not point production password resets or real customer mail at them. They exist for test traffic and throwaway signups, and the short retention window is a feature of that design rather than a limitation to work around.