Temp mail API: create disposable inboxes programmatically

A temp mail API is an HTTP interface for creating throwaway email inboxes on demand, reading the messages that arrive at them, and destroying them when you are done. Instead of opening a temp-mail website in a browser and copying an address by hand, you make a request, get back a live address, and poll or subscribe for inbound mail - all from code. It is the standard tool for automating one-time-password (OTP) retrieval, testing signup and email-verification flows, and QA where a fresh, isolated mailbox per run matters.

Most temp mail APIs are receive-only: they hand you a random inbox, let you read whatever lands in it, and expire it after a while. That is exactly right for a lot of jobs. This guide covers those jobs honestly - and then shows what changes when an inbox can also send, persist as long as you want, and be deleted the instant a task finishes.

What is a temp mail API?

A temp mail API turns a disposable inbox into a resource you allocate at runtime, like a database row or a cache key. You call an endpoint, you get an address, and you have programmatic access to everything that arrives at it. The classic use cases are:

• OTP and email-verification testing - sign up a test user, then read the confirmation code out of the inbox automatically.
• Signup and onboarding QA - run the same registration flow a hundred times, each with a clean address, without polluting a real mailbox.
• Scraping past email gates - some flows will not proceed until an address is verified, so an automated pipeline needs a real inbox to receive the link.
• Per-task isolation - give each test run, each customer, or each agent its own address so mail never crosses wires.

The value is that the address is real and the mail is real - you are not mocking an SMTP server, you are receiving actual delivered email through an API.

How do you create a temporary inbox with an API?

Here is the full loop with AgenticEmail: create an inbox, wait for mail, read it, and tear it down. Every request authenticates with a bearer token (Authorization: Bearer $AGENTICEMAIL_API_KEY, where keys look like am_...).

1. Create the inbox

curl -X POST https://api.agenticemail.dev/v1/inboxes \
  -H "Authorization: Bearer $AGENTICEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "username": "qa-runner-42" }'

The response contains a live address like qa-runner-42@inbox.agenticemail.dev. Omit username to get a random one, which is the usual choice for throwaway inboxes. On paid plans you can pass a verified custom domain so the address lands on your own domain instead.

2. Read the messages

Inbound mail arrives already parsed - sender, subject, text, HTML, and attachments as structured JSON. There is no MIME parsing to do on your side.

curl https://api.agenticemail.dev/v1/inboxes/ibx_123/messages \
  -H "Authorization: Bearer $AGENTICEMAIL_API_KEY"

If you are hunting for one specific message - say the OTP email from a particular sender - use the search endpoint instead of listing everything:

curl "https://api.agenticemail.dev/v1/inboxes/ibx_123/messages/search?q=verification" \
  -H "Authorization: Bearer $AGENTICEMAIL_API_KEY"

3. Do the same thing from your code

The official SDKs (npm install agenticemail or pip install agenticemail) wrap the same endpoints. Here is the create-then-read loop in TypeScript:

import AgenticEmail from "agenticemail";

const client = new AgenticEmail({ apiKey: process.env.AGENTICEMAIL_API_KEY });

// Create a throwaway inbox for this test run
const inbox = await client.inboxes.create({ username: "qa-runner-42" });
console.log(inbox.address); // qa-runner-42@inbox.agenticemail.dev

// Trigger your signup flow against inbox.address, then read what arrives
const { messages } = await client.messages.list({ inboxId: inbox.id });
for (const m of messages) {
  console.log(m.from, m.subject, m.text);
}

And the same in Python:

import os
from agenticemail import AgenticEmail

client = AgenticEmail(api_key=os.environ["AGENTICEMAIL_API_KEY"])

inbox = client.inboxes.create(username="qa-runner-42")
print(inbox.address)  # qa-runner-42@inbox.agenticemail.dev

result = client.messages.list(inbox_id=inbox.id)
for m in result.messages:
    print(m.from_, m.subject, m.text)

4. Delete the inbox when the task is done

This is the part that matters for the disposable pattern. Rather than waiting for an address to age out on someone else's schedule, you destroy it yourself the moment the run finishes:

curl -X DELETE https://api.agenticemail.dev/v1/inboxes/ibx_123 \
  -H "Authorization: Bearer $AGENTICEMAIL_API_KEY"

Create per task, DELETE when done. That is the auto-expiring pattern without the wait - you control the lifetime, so nothing lingers and nothing disappears out from under you mid-test.

Should you poll or subscribe for new mail?

Polling the messages endpoint in a loop is fine for a quick test script. For anything that runs continuously, push beats poll:

• Webhooks - register an HTTPS endpoint with POST /v1/webhooks and body { "url": "...", "event_types": ["message.received"] }. Each inbound message is delivered as a signed JSON payload (signed per the Standard Webhooks spec, so you can verify authenticity). More on this in the email webhook guide.
• WebSocket - connect to wss://api.agenticemail.dev/v1/events?token=am_... and receive the same parsed payloads on a long-lived connection, which suits agents that are already running.

Receive-only temp mail APIs vs a full inbox API

Not every job needs a full mailbox. Here is where the line sits.

Be honest about fit. If all you need is to pull an OTP out of a mailbox during a test and you never send anything, a free receive-only service such as temp-mail.org or the Mail.tm API does the job at zero cost, and you should use it. Reach for a full inbox API when the inbox has to send as well as receive, hold a real back-and-forth, live on your own domain, or persist under your control rather than expiring on a fixed timer.

When a disposable inbox needs to send back

The temp-mail model quietly assumes email only flows one direction: in. Real automation often needs the other direction too. An agent verifying its own signup has to click a link, sure - but an agent negotiating with a supplier, running support, or confirming an order has to reply. With AgenticEmail the same disposable inbox sends with one call:

curl -X POST https://api.agenticemail.dev/v1/inboxes/ibx_123/messages/send \
  -H "Authorization: Bearer $AGENTICEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "supplier@example.com", "subject": "Order 8842", "text": "Confirming quantity and ship date." }'

That is the upgrade path: start with throwaway inboxes for testing, and when the same code needs to talk back, nothing about the integration changes except that send is now available. This is the whole idea behind giving your agent an inbox - and the reasoning for why agents need their own email infrastructure rather than a borrowed Gmail account.

You can start on the free tier and read the full endpoint reference in the docs.

Frequently asked questions

Is there a free temp mail API?

Yes. Several receive-only services offer free temp mail APIs for pulling OTPs and testing signups, including the Mail.tm API and temp-mail.org (as of July 2026). AgenticEmail has a free tier as well, and adds sending, custom domains, and on-demand deletion on top of the receive-only basics.

Can a temp mail API send email?

Most cannot - classic temp mail APIs are receive-only throwaway inboxes built purely for reading incoming mail. AgenticEmail inboxes send and receive, so the same disposable address can reply, confirm, or start a thread with one send call.

How long do temporary inboxes last?

On receive-only services, inboxes usually auto-expire after a fixed window - often minutes to a day - and you cannot extend them. With AgenticEmail you control the lifetime: an inbox persists until you delete it with DELETE /v1/inboxes/{inbox_id}, so it lasts exactly as long as your task needs and not a second past it.

How do I get the OTP or verification code out of the inbox?

Read the inbox with the messages endpoint or subscribe to a webhook, then extract the code from the parsed text or html field with a regular expression. Because inbound mail arrives already parsed, you never touch raw MIME - the sender, subject, and body are plain JSON fields.

Is a temp mail API the same as a disposable email API?

They refer to the same thing: an API for creating short-lived, throwaway email addresses. "Temp mail API," "temporary email API," and "disposable email API" are used interchangeably. The meaningful difference between products is receive-only versus full send-and-receive, not the label.

Can I use a temp mail API with an AI agent?

Yes, and it is a primary use case for a full inbox API. An agent can create an inbox per task, receive parsed mail over webhooks or WebSocket, reply, and delete the inbox when finished - all through the same REST endpoints, or through the best email API surface your framework already speaks.