Overview
The Supermail Gateway API — authorize with OAuth 2.1, then read and manage connected mailboxes through one token-authenticated API.
The Supermail Gateway API lets your application connect email mailboxes and consume a normalized stream of what happens inside them — new messages, message changes, folder changes, and sync progress — without ever touching IMAP, Gmail, or Microsoft Graph directly. Supermail handles provider authentication, syncing, and event delivery; your app talks to one API.
The integration has two parts:
Authorization (OAuth 2.1 / OIDC)
Your app obtains a user's consent through the standard authorization-code + PKCE flow and receives a Supermail access token scoped to exactly what the user approved.
Delegated portal login
A trusted confidential app can provision an app-local user or link an existing account, then create a short-lived, one-time portal login URL.
Resource API
With that token you call the API: list and manage mailboxes, and list, fetch their retained events and configure webhook delivery. Structured calls use JSON-RPC.
How it works
- Register your application to obtain a
client_id, an optionalclient_secret, one or more exact redirect URIs, and the set of scopes it may request. Mark the capabilities every grant must contain as required; the remaining registered scopes are recommended. - Send the user through the authorization flow. They pick which mailbox(es) your app may reach. Required and recommended capabilities begin selected; the user may remove recommended ones. Supermail redirects back with an authorization code.
- Exchange the code for tokens at the token endpoint —
an
id_token, a short-lived access token, and a rotating refresh token. - Call the Resource API with the access token to manage mailboxes and consume their events.
Base URL
Every path in this reference is relative to your deployment's base URL — the same origin that serves the OAuth issuer and every redirect URI. Throughout the docs it is written as:
https://supermail.example.comThe JSON-RPC and raw HTTP endpoints share one origin.
Conventions
- JSON payloads use the native Rust DTO projection with
snake_casefield names (the wire is snake_case everywhere — never camelCase),oneofarms as sibling keys, enums as their string names, and timestamps as RFC 3339 (rendered with a+00:00offset). - IDs are opaque, prefixed strings (
account_…,event_…,content_…) — match the prefix to route, but never parse structure out of an id. - The one error model is shared across every surface — see Errors.
New here? Read Authentication and Authorization first — they explain the token you carry and the scopes that decide what it can do.
If your application already authenticates its own users and needs to open the Supermail portal for them, use the separate delegated-login flow. It hands the user into the portal without granting your app Resource API access.