API for test scripts

Every inbox can be read as JSON, so a Selenium or Playwright test can sign up with anything@usac-test.appspotmail.com, wait for the email, and read the code or link from it.

Access

Public inboxes need no key. Private inboxes need one of these, sent as an HTTP header:

X-Inbox-Key: <key>: the key shown when that inbox was made private.
X-API-Key: <admin key>: the admin key from the admin page. It opens every inbox.

Requests that change something (delete, make private) also need either an X-API-Key header or X-Requested-With: tempmail.

Endpoints

Request	What it returns
`GET /api/inbox/{name}/wait`	Waits for the next email and returns it. Options: `timeout` (seconds, max 120, default 60), `since` (ISO time or unix seconds; default is 60 seconds ago), `subject` and `from` (text the subject or sender must contain). Returns 408 if nothing arrives in time.
`GET /api/inbox/{name}/latest`	The newest email, or 404 if the inbox is empty.
`GET /api/inbox/{name}`	The inbox: up to `limit` (max 50) message summaries, newest first.
`GET /api/message/{uuid}`	One email in full. Add `?peek=1` to leave it unread.
`GET /api/message/{uuid}/raw`	The original email source, with all headers.
`DELETE /api/message/{uuid}`	Deletes one email.
`DELETE /api/inbox/{name}`	Deletes every email in the inbox.
`POST /api/inbox/{name}/claim`	Makes a public inbox private and returns its `key` (shown once).

An email in JSON

{
  "uuid": "4f0c…",
  "subject": "Confirm your account",
  "from": "E-File <no-reply@example.org>",
  "to": "test1@usac-test.appspotmail.com",
  "date": "2026-10-17T22:04:11Z",
  "codes": ["482913"],
  "links": [{"url": "https://example.org/verify?t=…", "text": "Verify email", "action": true}],
  "text": "Your code is 482913 …",
  "attachments": [{"name": "letter.pdf", "size": 48211, "url": "/attachment/4f0c…/0"}]
}

codes lists likely verification codes, best guess first. In links, action: true marks links that look like verify, confirm, reset or sign-in links.

Examples

curl

curl "https://usac-test.appspot.com/api/inbox/test1/wait?timeout=60&subject=confirm"

Java (11+)

// Note the time BEFORE the step that sends the email, so a fast email is not missed
String since = java.time.Instant.now().toString();

// ... click "Register" in Selenium here ...

var client = java.net.http.HttpClient.newHttpClient();
var req = java.net.http.HttpRequest.newBuilder(java.net.URI.create(
        "https://usac-test.appspot.com/api/inbox/test1/wait?timeout=90&since=" + since))
    .header("X-API-Key", System.getenv("TEMPMAIL_KEY"))   // only for private inboxes
    .timeout(java.time.Duration.ofSeconds(100))
    .build();
var resp = client.send(req, java.net.http.HttpResponse.BodyHandlers.ofString());
if (resp.statusCode() != 200) throw new AssertionError("No email: " + resp.body());

// The first code, without a JSON library:
var m = java.util.regex.Pattern.compile("\"codes\":\\s*\\[\"([^\"]+)\"").matcher(resp.body());
String code = m.find() ? m.group(1) : null;

Python

import datetime, requests
since = datetime.datetime.now(datetime.timezone.utc).isoformat()
# ... trigger the email ...
r = requests.get("https://usac-test.appspot.com/api/inbox/test1/wait",
                 params={"timeout": 90, "since": since},
                 headers={"X-API-Key": "…"}, timeout=100)
r.raise_for_status()
code = r.json()["codes"][0]