Handle email OAuth callback

curl --request GET \
  --url https://your-instance.example.com/api/email/oauth/callback

{
  "message": "Missing code or state",
  "error": "bad_request"
}

Handle email OAuth callback

Provider redirect target. Exchanges the authorization code for tokens, persists or refreshes the EmailAccount, sets up mailbox watch (Gmail Pub/Sub or Outlook Graph subscription) when configured, then 302-redirects to the client settings page with ?provider=<name>&status=success|error. This route is public (no bearer auth) — the userId/organizationId come from the signed OAuth state. Only the pre-redirect validation failures surface as JSON (400). On a downstream failure the user is still 302-redirected back to the settings page with status=error.

GET

api

oauth

callback

Handle email OAuth callback

curl --request GET \
  --url https://your-instance.example.com/api/email/oauth/callback

{
  "message": "Missing code or state",
  "error": "bad_request"
}

Query Parameters

code

string

Authorization code returned by the provider.

state

string

Base64-encoded JSON { userId, organizationId, provider } echoed back by the provider.

Response

Redirect to ${CLIENT_URL}/settings?provider=<name>&status=success on success, or ${CLIENT_URL}/settings?status=error on failure. Frontends should observe the provider and status query parameters on the resulting settings page to surface the outcome to the user.

Initiate email OAuth authorization flow Gmail Pub/Sub push webhook

⌘I