What a temp mail API is — and who actually needs one

A temp mail website vs a temp mail API

A temp mail website is the thing you already know: open a page, get a throwaway inbox, read the mail in a browser. A human is in the loop the whole time.

A temp mail API is the same disposable-mailbox idea exposed as HTTP endpoints, so a program can do it instead of a person. Your code asks for a fresh address, your code reads the messages that arrive, your code throws the mailbox away — no browser, no clicking.

That single difference — code instead of a human — is what makes it useful, and it is also what narrows down who actually needs one.

Who needs one

Three groups, in roughly descending order:

• QA and CI pipelines. This is the big one. Automated tests that exercise a real signup, email-verification or password-reset flow need an inbox that exists, receives mail, and does not collide with other test runs. A temp mail API gives every test run its own fresh mailbox. We wrote a step-by-step Playwright guide for exactly this.
• Automation and tooling. Anything that programmatically registers accounts, scrapes a confirmation link, or monitors deliverability of your own transactional mail. If a script needs to receive a message, a temp mail API is how it does so without a real mailbox.
• Developers prototyping. Building an onboarding flow and want to see the verification mail land without wiring up a personal inbox or a heavyweight local mail server (Mailpit, MailHog). An API call is faster than configuring a service.

If you just need one inbox for one signup right now, you do not need an API — use the website. The API earns its place the moment the task repeats or has to run unattended.

Your first call against the Mailiy API

The Mailiy REST API lives at api.mailiy.com and uses bearer-token auth. Mint a key in your account settings (it is prefixed ml_pk_) and keep it in a secret store, not your repo.

Create a mailbox:

curl -X POST https://api.mailiy.com/v1/mailbox \
  -H "Authorization: Bearer $MAILIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlMinutes": 30}'

You get back an id and an address. Use the address wherever you need it, then read what arrived:

curl https://api.mailiy.com/v1/mailbox/$ID/messages \
  -H "Authorization: Bearer $MAILIY_API_KEY"

Poll that endpoint on a short interval until messages is non-empty — mail usually shows up in under a second after SMTP arrival. When you are done, DELETE /v1/mailbox/:id to clean up, or just let the TTL expire it.

That is the whole core API: create, read, delete. There is also POST /v1/webhooks if you would rather be pushed incoming mail than poll for it.

What it costs

The API is metered per tier — and the free tier is genuinely usable, not a teaser:

A typical PR pipeline burns 3–5 calls per test (create, poll, optional delete). At 50 tests that is a couple hundred calls a run — the free tier covers a small CI suite outright, and api_pro covers a serious one. Business goes to 1,000 req/min and Enterprise is unmetered.

In short

A temp mail API is disposable email for programs instead of people. If your task is one-off and manual, the website is all you need. If it repeats, runs in CI, or has to work unattended, the API is the point — and you can make your first call against the Mailiy API on the free tier today, no card required.

Try it now → Generate a disposable address on the mailiy homepage — one click, ready in under two seconds, no signup, no account.