Overview

The Resource API is where your app does its work once it holds an access token: manage mailboxes and consume their events. Every call carries the bearer token and is checked against the live grant.

Transports

Native Rust DTOs and a closed method registry define the API. Structured operations use JSON-RPC; large content uses dedicated HTTP routes; event consumers receive signed HTTPS webhook pushes.

See Transports for the addressing, envelope, batching, and the matrix of which operations each transport supports.

The OpenAPI 3.1 document, JSON-RPC method registry and enum-field registry (whether each enum-valued field is open to values added later or strict; see Events) are reviewed projections of that Rust authority and checked for drift in CI. Typed webhook payloads are exported alongside them by the @traummail/gateway-types TypeScript package, whose EventPayloadMap maps each event type to its payload.

Payload conventions

Structured JSON payloads follow these conventions:

• Field names are snake_case — account_id, next_page_token, email_received. Never camelCase.
• Enums serialize as their full string name — ACCOUNT_LIFECYCLE_ACTIVE, IMAP_SECURITY_TLS.
• oneof arms appear as sibling keys; exactly one is present.
• Timestamps are RFC 3339 with an explicit offset (2026-06-17T08:14:03+00:00).
• IDs are opaque, prefixed strings — account_…, event_…, content_…. Match the prefix to route; never parse the rest. Both prefixed and bare forms are accepted on input.

Methods & scopes

The scope shown is the capability the live grant must carry; a missing capability is a PERMISSION_DENIED error. Write methods also check the account's live working.modify / working.send; a grant never widens a read-only or temporarily unavailable connection.

There is no reconnect method here. Connecting a mailbox is always the AccountConnections/prepare → start/complete_classical flow. A reconnect targets an existing binding and advances its generation; creating another logical account is never a repair fallback.

Next