Developer API

Build on ZERO Mail

A JMAP-native mail API behind ZERO ID OAuth. Read, send, and embed mail in your own app.

01Quickstart

1.Register an OAuth client with ZERO ID and request the mail.read / mail.send scopes.
2.Send the user through Authorization Code + PKCE to obtain an access token.
3.Call the REST API at https://api.zero.sc/v1 with the Bearer token.
4.Or embed the compose widget with a single iframe — no backend required.

authorize

GET https://auth.zero.sc/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your.app/callback
  &scope=openid%20mail.read%20mail.send
  &code_challenge=BASE64URL(SHA256(verifier))
  &code_challenge_method=S256

token

curl -X POST https://auth.zero.sc/oauth/token \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d code_verifier=PKCE_VERIFIER \
  -d redirect_uri=https://your.app/callback \
  -d client_id=YOUR_CLIENT_ID
# → { "access_token": "...", "token_type": "Bearer", "expires_in": 900 }

02Endpoints

GET/v1/meCurrent identity — zid, handle, address, name, scopes.

GET/v1/mailboxesList mailboxes (inbox, sent, drafts, …).

GET/v1/threadsList conversation threads in a folder.

GET/v1/messages/:idFetch a single message with body and attachments.

POST/v1/messagesSend (or schedule) a message.

GET/v1/labelsList labels.

POST/v1/mailbox/provisionProvision the caller’s mailbox on first use.

03Grants

authorization_code

Authorization Code + PKCE

User-facing apps. The user signs in with ZERO ID; your app never sees a password.

client_credentials

Client Credentials

Server-to-server (M2M). For trusted backends that send on their own behalf.

04Scopes

mail.readRead mailboxes, threads, and messages.

mail.sendSend and schedule messages.

openid profileIdentify the signed-in user (zid, handle).

05Send mail (REST)

POST /v1/messages

curl -X POST https://api.zero.sc/v1/messages \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["someone@example.com"],
    "subject": "Hello from ZERO Mail",
    "text": "Sent through the ZERO Mail API."
  }'

06Embed in your app

Drop a compose window into any site with an iframe, or call the REST API directly with a Bearer token.

Compose widget (iframe)

<!-- Drop a compose window into any page -->
<iframe
  src="https://mail.zero.sc/embed/compose?to=hello@zero.sc"
  width="480" height="600"
  style="border:1px solid var(--border)"
  title="ZERO Mail — compose">
</iframe>

Send via REST

curl -X POST https://api.zero.sc/v1/messages \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["someone@example.com"],
    "subject": "Hello from ZERO Mail",
    "text": "Sent through the ZERO Mail API."
  }'

Preview

Start building with ZERO Mail

Get a client Back to mail