Architecture

Supermail sits between your application and the email providers it connects to. Your app authorizes once, then works entirely against Supermail's own model — never IMAP sessions, OAuth refresh tokens, or provider-specific quirks.

   Your app ──OAuth (authorize / consent / token)──▶ ┌───────────┐
            ◀──────── access token ───────────────── │           │
   Your app ──Resource API (access token)──────────▶ │ Supermail │ ──▶ Provider
            ◀──────── accounts · events ──────────── │           │      (IMAP /
                                                      └───────────┘       Gmail /
                                                                          Graph)

The object model

Everything in the API is one of a few objects:

• Account — the logical aggregate and event partition. It composes role-qualified service bindings and can outlive any individual provider credential or transport. Your app can list, create, update, disconnect, and purge accounts a user granted it.
• Service binding — one provider adapter occupying one account role. Its lifecycle, capabilities, freshness, authority, and generation are tracked independently. External resources are reserved durably and conflicts never disclose the reservation owner.
• Event — an immutable record of one observed change on an account: a message received, updated or deleted; a folder change; or sync progress. Events form a per-account, ordered log your app reads or tails.
• Grant — a user's standing authorization of your app: which account(s) it may reach and with which scopes. A grant is created when the user consents and can be revoked at any time.

How a request flows

1. Your app calls the API with its access token.
2. Supermail verifies the token and re-resolves the live grant it names — the token never carries standing authority on its own.
3. The grant is checked against the account and capability the request needs.
4. Supermail performs the work against the underlying provider and returns a normalized result.

Because the grant is resolved fresh on every call, an authorization change is effective immediately: revoking or narrowing a grant takes effect on the very next request, well inside the access token's lifetime. See Authorization.

Two ways to consume event information

• Read — list retained account history through the Resource API.
• Push — configure a named consumer with one signed HTTPS webhook. Gateway owns its cursor and retries until the endpoint accepts the delivery.

Single-tenant by design

A Supermail deployment serves one operator and one consuming application. There are no organizations or tenants in the API — a user owns accounts, apps are authorized against those accounts by grants, and that ownership graph is the entire authorization model.