Skip to content
SuperMail docs

API overview

Shape

SuperMail exposes a single GraphQL endpoint. The same schema powers the web and mobile apps. There is no separate REST surface today (a few internal endpoints exist for background sync and webhooks, but those are not part of the public API).

GraphQL endpoint:

POST https://api.supermail.app/graphql

Authentication

The API authenticates via the same Supabase JWT your browser session uses. Send it as a bearer token:

Terminal window
curl -H "Authorization: Bearer $SUPERMAIL_JWT" \
  -H "Content-Type: application/json" \
  https://api.supermail.app/graphql \
  -d '{"query": "{ getProfile { id email } }"}'

Today there is no first-class “long-lived API token” surface in Settings - you authenticate with the same JWT the app uses.

Rate limits

  • GraphQL: 100 requests / minute per IP.

Exceeding the limit returns 429. Back off and retry.

Schema

Every query and mutation the app uses is part of the schema. Run an introspection query against the GraphQL endpoint to discover the full surface, or browse the schema in the repo at common/schema.graphql.

Webhooks and streaming

Outbound webhooks (new mail, thread updated, etc.) and a streaming firehose are not implemented today. If you need real-time updates, poll the relevant getEmails / getThread queries.

Feedback

If you’re building something on this, email api@supermail.app. We’d rather hear about rough edges early.