Read-Only Mail API (Parsed)
Endorsed stable surface
The three endpoints below are Spare.Email's endorsed, read-only API surface. They are the same endpoints the official MCP server spare-email-mcp consumes, and the response shapes shown here are verified against Spare.Email. Anything not on this page is explicitly not endorsed for external consumers: mailbox creation, sending, deletion and admin endpoints may change at any time or require the web UI, and no client should build on them.
These endpoints return parsed mail (readable subject, text, html, attachment metadata), unlike the raw endpoints covered in View Email API. They work with any up-to-date cloudflare_temp_email deployment — point them at your own worker URL for self-hosted instances. Handlers are byte-identical to upstream main at the time of writing; upstream may continue to evolve the parsed format, so treat Spare.Email as the reference deployment and re-verify on upstream syncs.
Authentication
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <address_jwt> — the mailbox credential (Address JWT) |
x-custom-auth | If enabled | Your site-wide access password, when the deployment sets PASSWORDS |
x-lang | No | Preferred language for error messages (en / zh) |
The Address JWT is the complete key to one mailbox: anyone holding it can read that mailbox's mail and nothing else. There is no other identity layer — keep the credential secret.
GET /api/settings
Resolves the credential to its mailbox and returns the mailbox state:
curl -H "Authorization: Bearer $JWT" https://spare.email/api/settings{
"address": "[email protected]",
"send_balance": 0,
"new_address_token": null,
"expire_at": null
}| Field | Type | Description |
|---|---|---|
address | string | The mailbox address this credential opens |
send_balance | number | Outbound send balance (always 0 on receive-only instances) |
new_address_token | string | null | Replacement credential when the deployment issues rotated tokens; null means keep using your current JWT |
expire_at | number | null | Unix timestamp (seconds) of user-set expiry; null = no custom expiry |
GET /api/parsed_mails
Paginated parsed inbox, newest first:
curl -H "Authorization: Bearer $JWT" "https://spare.email/api/parsed_mails?limit=20&offset=0"| Parameter | Range | Notes |
|---|---|---|
limit | 1–100 | Integer; outside the range returns a 400 text error (Invalid limit) |
offset | ≥ 0 | Integer; negative or missing returns a 400 text error (Invalid offset) |
{
"results": [
{
"id": 1,
"message_id": "<[email protected]>",
"source": "[email protected]",
"address": "[email protected]",
"metadata": null,
"is_unread": null,
"created_at": "2026-11-16 08:26:37",
"sender": "Example Sender <[email protected]>",
"subject": "Your verification code",
"text": "Your verification code is 123456",
"html": "<html>…</html>",
"attachments": [
{ "filename": "invoice.pdf", "mimeType": "application/pdf", "disposition": "attachment", "size": 27412 }
]
}
],
"count": 1
}Row fields are additive: metadata, is_unread and attachment disposition may be null/absent on deployments that predate the corresponding database patches. The raw source field is never returned by the parsed endpoints.
Pagination: count is only computed on the first page
count (the total number of mails in the mailbox) is queried only when offset=0. Later pages return count: 0 — retain the total from the first page when paginating.
GET /api/parsed_mail/:id
One parsed message, same row shape (without pagination wrapping):
curl -H "Authorization: Bearer $JWT" https://spare.email/api/parsed_mail/1- A mail belonging to another address (or otherwise not found) returns HTTP 200 with a
nullbody — this is deliberate: mail IDs are not confirmable to unknown credentials. Check for a null body, not for 404. - The response never includes the raw RFC822 source; use the raw endpoints in View Email API if you want to parse it yourself.
Error semantics
| Case | Response |
|---|---|
Missing/invalid JWT, or missing x-custom-auth when required | 401 with a message |
limit/offset out of range | 400 with a translated text error |
| Mail not found (or wrong credential) | 200 with body null |
| Zone-level throttling (Cloudflare) | 429 — back off and retry with increasing delay |
There is no dedicated rate limit on these read endpoints in the worker itself; upstream rate limiting applies only to creation/sending endpoints. Polling clients should still be polite: an interval of a few seconds is more than enough.
Waiting for OTP codes (client-side pattern)
There is no wait/OTP endpoint — waiting is a polling discipline on the list/read endpoints, which is exactly what wait_for_otp in spare-email-mcp implements:
- Note the highest mail
idyou have seen. - Poll
GET /api/parsed_mailsevery 3–30 seconds (respecting your own timeout, e.g. 10 minutes). - Treat any
429as a backoff signal. - Match new mails against your filter (e.g. subject contains "code") and extract the code from
subjector strippedtext/html.
What is deliberately not part of this surface
POST /api/new_address (mailbox creation), POST /api/send_mail (where enabled), POST /api/expire, DELETE flows, and everything under /admin/* are not endorsed for external API consumers and may change without notice. Create mailboxes in the web UI; report abuse to [email protected].
See also
- AI Agent Mailbox Usage — agent patterns and consent cautions
- Mailbox Expiry API — Spare.Email's per-mailbox expiry extension
- spare-email-mcp on GitHub — reference MCP client of this API