Temp Email REST API
REST API phrasing signals a more technical audience. This page is built to match developers who are thinking about inbox automation and workflow integration.
The Temp Postal REST API is a small, predictable surface: create an inbox, list its messages, fetch one message, delete the inbox. Requests authenticate with a bearer token over HTTPS, responses are JSON, and errors use standard status codes with a machine-readable reason.
- Four endpoints cover the whole lifecycle of a test inbox
- JSON responses expose headers, plain text and HTML bodies
- 429 responses carry Retry-After; limits are per key
- Deleting an inbox is immediate and irreversible
Best-fit use cases
How teams evaluate this workflow
Searchers landing on this page are usually not browsing casually. They are comparing workflow fit, trust, feature coverage, and whether temporary email solves a real operational pain point for their team or use case.
The most useful evaluation lens is practical: how quickly a disposable inbox can be created, whether the workflow is predictable enough for testing or privacy use, how clearly the service explains its positioning, and whether the product leaves room for future scaling into more advanced use cases.
In other words, high-quality decision pages should reduce uncertainty. They should tell a visitor who this page is for, which jobs temporary email can genuinely help with, and where expectations need to stay realistic.
Questions to answer before adopting it
In depth
Designing your client around the lifecycle
Wrap the API in four functions that mirror the lifecycle rather than the endpoints: openInbox, waitForMessage, readMessage, closeInbox. The interesting logic lives in waitForMessage - interval, timeout, and a predicate that matches the sender or subject you actually expect - and keeping it in one place means every test inherits the same retry semantics and the same helpful failure message.
Always close the inbox in a teardown that runs even when the test fails. Retention will clean up eventually, but explicit deletion keeps usage counts honest and stops a failed run leaving live addresses behind.
Handling errors without hiding them
Retry on 429 and 5xx with backoff, respecting Retry-After when it is present. Do not retry on 4xx - a 401 means the key is wrong and a 404 means the inbox is gone, and retrying either just delays a clear error by thirty seconds.
Surface the response body in test failures. An assertion that says 'expected verification mail, got 401 invalid_key' points at the missing environment variable immediately; one that says 'timeout after 30s' sends someone to read the application logs for nothing.
Rate limits and parallel suites
Limits are enforced per key, so the arithmetic is straightforward: total request rate is roughly your parallel job count multiplied by the poll frequency. If a wide matrix pushes you into 429s, lengthen the poll interval before you ask for a higher limit - most suites poll far more often than message delivery warrants.
For very wide matrices, one key per job group spreads the limit and, more usefully, makes it obvious in the dashboard which group is responsible when usage spikes.
Frequently asked questions
Why target REST API wording specifically?
Because it captures more technical search intent from developers who already know they want programmatic control rather than a casual disposable inbox.
Does this page need full API docs?
No. It mainly needs accurate positioning, clear expectations, and a logical next step toward the main product or API section.
Is this useful even before a full API rollout?
Yes, as long as the copy stays honest and frames the page as an evaluation or intent-matching resource rather than unsupported product documentation.
Quick answer
What does the temp email REST API cover, and how do webhooks fit in?
- Webhooks remove polling entirely for event-driven systems, pushing a payload to your endpoint the moment a message arrives.
- Delivery history is recorded per webhook, so failed or delayed pushes are visible rather than silently lost.
- REST endpoints remain available as a fallback even when webhooks are configured, so a missed push does not mean a missed message.
- Raw message source is accessible via the API for header-level checks such as SPF and DKIM results.
REST endpoints as the foundation
The API's core resources are addresses and messages, reached through standard REST verbs: POST to create an address, GET to list messages for it, and GET again to fetch a single message by ID. This is deliberately unsurprising - anyone who has integrated with a typical SaaS REST API already knows the shape of these calls before reading a line of documentation.
Every response includes the fields most integrations need immediately - sender, recipient, subject, timestamps, plain-text and HTML bodies - without requiring a second call to fetch a body separately. For deeper inspection, the raw message source is available on the same resource, so header-level details do not need a different endpoint or authentication scope.
Rate limits apply per key at the REST layer regardless of whether webhooks are also configured, since even webhook-driven integrations typically still make occasional REST calls, for example to create addresses or to re-fetch a message the webhook payload only summarised.
Configuring and trusting webhook delivery
A webhook is configured against an address, pointing at an HTTPS endpoint you control. When a new message arrives for that address, the API sends a payload to that endpoint describing the message, which your application can process immediately rather than waiting for the next poll cycle. This is the natural fit for event-driven backends that already process other events, such as payment webhooks, through the same pipeline.
Because network calls to your endpoint can fail - a deploy in progress, a transient DNS issue, an endpoint that is briefly overloaded - delivery history is recorded per webhook, showing attempts, response codes and timestamps. That history is what lets you distinguish 'the message never arrived' from 'the message arrived but our endpoint was down when the webhook fired', which are very different problems to debug.
Because webhook delivery is not guaranteed to be instantaneous or infallible in any system, it is worth treating it as an optimisation over polling rather than a total replacement for the REST fallback: if your endpoint's logs show a gap, the same message is still retrievable directly through the list-messages endpoint using the address it was sent to.
Combining REST and webhooks in a single integration
A common pattern is to use REST for address creation and initial setup, since that happens once per test case or per user signup, and webhooks for message arrival, since that is the part with unpredictable timing where polling wastes both API quota and wall-clock time. This split plays to each mechanism's strength rather than picking one exclusively.
For CI pipelines specifically, webhooks can be more awkward than they first appear, because CI runners are often short-lived and not reachable from the internet by a webhook push. A frequent solution is polling within the CI job itself, since the job only needs to wait a few seconds anyway, while a long-running backend service handling real user signups uses webhooks because it is already listening for other events continuously.
Whichever mechanism drives message arrival, the same downstream code should handle the resulting message object - parsing the body, extracting a code or link, and asserting on content - so switching between polling and webhook delivery later is a matter of changing how the message reaches your handler, not rewriting what the handler does with it.
Frequently asked questions
Do I need a public HTTPS endpoint to use webhooks?
Yes, the webhook target must be reachable over HTTPS from the internet. For local development, a tunnelling tool that exposes a local port publicly is the usual way to test webhook delivery before deploying the receiving endpoint.
What happens if my webhook endpoint is down when a message arrives?
The delivery attempt is recorded as failed in the webhook's delivery history, and the message itself remains retrievable through the REST API regardless, so nothing is lost even if the push itself did not land.
Can I use both polling and webhooks for the same address?
Yes, they are not mutually exclusive. Some teams poll during initial development and testing, then switch to webhooks once the integration is stable, without needing to change how addresses are created.
Is webhook payload content the same as the REST message object?
The webhook payload describes the message that arrived, and the full message content including raw source is retrievable via the REST API using the identifier included in that payload, so you are not limited to whatever fields the webhook itself carries.
How do I check SPF and DKIM results for a received message via the API?
The raw message source returned by the message endpoint includes the headers recorded at delivery, which contain the authentication results a receiving mail server checked, letting you verify SPF and DKIM outcomes as part of a deliverability test rather than inspecting them manually.