Skip to content

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 ​

HeaderRequiredDescription
AuthorizationYesBearer <address_jwt> — the mailbox credential (Address JWT)
x-custom-authIf enabledYour site-wide access password, when the deployment sets PASSWORDS
x-langNoPreferred 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:

bash
curl -H "Authorization: Bearer $JWT" https://spare.email/api/settings
json
{
  "address": "[email protected]",
  "send_balance": 0,
  "new_address_token": null,
  "expire_at": null
}
FieldTypeDescription
addressstringThe mailbox address this credential opens
send_balancenumberOutbound send balance (always 0 on receive-only instances)
new_address_tokenstring | nullReplacement credential when the deployment issues rotated tokens; null means keep using your current JWT
expire_atnumber | nullUnix timestamp (seconds) of user-set expiry; null = no custom expiry

GET /api/parsed_mails ​

Paginated parsed inbox, newest first:

bash
curl -H "Authorization: Bearer $JWT" "https://spare.email/api/parsed_mails?limit=20&offset=0"
ParameterRangeNotes
limit1–100Integer; outside the range returns a 400 text error (Invalid limit)
offset≥ 0Integer; negative or missing returns a 400 text error (Invalid offset)
json
{
  "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):

bash
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 null body — 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 ​

CaseResponse
Missing/invalid JWT, or missing x-custom-auth when required401 with a message
limit/offset out of range400 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:

  1. Note the highest mail id you have seen.
  2. Poll GET /api/parsed_mails every 3–30 seconds (respecting your own timeout, e.g. 10 minutes).
  3. Treat any 429 as a backoff signal.
  4. Match new mails against your filter (e.g. subject contains "code") and extract the code from subject or stripped text/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 ​

Docs adapted from the MIT-licensed cloudflare_temp_email project — License & attribution