Email Import

Connect Email Provider (Initiate OAuth)

Initiate OAuth flow to connect user's email inbox.

Returns an oauth_url that you should redirect the user to. After authorization, they are redirected back to your redirect_uri with the following query parameters:

On success:

inbox_token - Encrypted token to store client-side
email - Email address of the connected account
state - Your original state parameter (for CSRF verification)

On error:

error - Error code (e.g., access_denied, token_exchange_failed)
state - Your original state parameter

Store the inbox_token client-side and use it for all subsequent inbox API calls. The token is long-lived (it stores an encrypted refresh token), so a single OAuth connect gives ongoing access to both historical and future CAS statements in the user's inbox. Reuse the same token until the user revokes access via /v4/inbox/disconnect or their provider's account settings.

post/v4/inbox/connect

Request body

provider'gmail' | 'outlook' | 'zoho'

Mail provider to connect. Defaults to gmail.

gmail - Google accounts: @gmail.com and Google Workspace domains.
outlook - personal Microsoft accounts: @outlook.com, @hotmail.com, @live.com, @msn.com and localised variants (@hotmail.co.uk, @live.in, @hotmail.fr). Any other address registered as a personal Microsoft account also works, including custom domains.
zoho - Zoho Mail accounts, including custom domains hosted on Zoho.

Any unrecognised value is treated as gmail. The resolved provider is returned in the response.

redirect_uristring uri required

Your callback URL to receive the inbox_token (must be http or https)

statestring

State parameter for CSRF protection (returned in redirect)

Example request

{
  "provider": "outlook",
  "redirect_uri": "https://yourapp.com/oauth-callback",
  "state": "abc123"
}

Response

OAuth URL generated successfully

expires_ininteger

Seconds until the OAuth URL expires (typically 10 minutes)

oauth_urlstring uri

Redirect user to this URL to start OAuth flow

provider'gmail' | 'outlook' | 'zoho'

The provider this OAuth URL was generated for

statusstring

Example response

{
  "expires_in": 600,
  "oauth_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...",
  "provider": "outlook",
  "status": "success"
}