Reference

HTTP API

Complete local HTTP API reference, including filters and response shapes.

Maintained by contributorsLast updated July 23, 2026

The local HTTP API returns JSON and is available at http://localhost:8025 by default.

Request conventions

Query values must be URL encoded. List, latest, and wait requests accept these filters:

Query	Meaning
`to`	Match any recipient address, case-insensitively
`subject`	Case-insensitive subject substring
`subjectPattern`	JavaScript regular-expression source for the subject
`subjectFlags`	Flags used with `subjectPattern`
`afterId`	Return only messages received after this stored message

limit is supported by the list route and must be from 1–100. timeoutMs is supported by the wait route and must be from 1–60,000. Errors return { "error": "..." } with an appropriate status.

Health

GET/health

Returns the bound SMTP and HTTP addresses plus the recipient domain.

{
  "ok": true,
  "api": { "host": "localhost", "port": 8025 },
  "smtp": { "host": "localhost", "port": 1025 },
  "domain": "local.test"
}

List emails

GET/api/emails

Returns matching messages in receive order. The response is { "emails": CapturedEmail[] }.

curl "http://localhost:8025/api/emails?to=signup%40local.test&limit=10"

Latest email

GET/api/emails/latest

Returns { "email": CapturedEmail } for the newest matching message. Returns 404 when no match exists.

curl "http://localhost:8025/api/emails/latest?subject=verify"

Wait for email

GET/api/emails/wait

Long-polls until a matching message is available. The default wait is 10 seconds and the maximum is 60 seconds. Returns { "email": CapturedEmail } on success or 408 on timeout.

curl "http://localhost:8025/api/emails/wait?to=signup%40local.test&timeoutMs=30000"

Get email by ID

GET/api/emails/:id

Returns { "email": CapturedEmail } for one stored identifier, or 404 when it is not present.

Clear emails

DELETE/api/emails

Deletes every stored message and returns { "deleted": number }. Add a to query to delete only messages addressed to one recipient.

curl -X DELETE "http://localhost:8025/api/emails?to=signup%40local.test"