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-sideemail- Email address of the connected accountstate- 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.
Authorizations
Your API key for authentication.
Use sandbox-with-json-responses as Sandbox key.
Body
Your callback URL to receive the inbox_token (must be http or https)
"https://yourapp.com/oauth-callback"
State parameter for CSRF protection (returned in redirect)
"abc123"
Mail provider to connect. Defaults to gmail.
gmail- Google accounts:@gmail.comand Google Workspace domains.outlook- personal Microsoft accounts:@outlook.com,@hotmail.com,@live.com,@msn.comand 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.
gmail, outlook, zoho "outlook"
Response
OAuth URL generated successfully
"success"
Redirect user to this URL to start OAuth flow
"https://accounts.google.com/o/oauth2/v2/auth?client_id=..."
The provider this OAuth URL was generated for
gmail, outlook, zoho "outlook"
Seconds until the OAuth URL expires (typically 10 minutes)
600

