---
title: "Connect Email Provider (Initiate OAuth)"
method: POST
path: "/v4/inbox/connect"
tags: ["Email Import"]
---

# Connect Email Provider (Initiate OAuth)

`POST /v4/inbox/connect`

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.

## Request body

- object
  - `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_uri` string, uri, required — Your callback URL to receive the inbox_token (must be http or https)
  - `state` string — State parameter for CSRF protection (returned in redirect)

## Response `200`

OAuth URL generated successfully

- object
  - `expires_in` integer — Seconds until the OAuth URL expires (typically 10 minutes)
  - `oauth_url` string, uri — Redirect user to this URL to start OAuth flow
  - `provider` 'gmail' | 'outlook' | 'zoho' — The provider this OAuth URL was generated for
  - `status` string

## Other responses

- `400` — Invalid or missing redirect_uri
- `401` — Unauthorized. This can happen if the `x-api-key` header is missing.

---

[API](https://skmtc.net/casparser/apis/cas-parser-track-portfolios-from-cdsl-nsdl-cams-kfintech.md) · [All operations](https://skmtc.net/casparser/apis/cas-parser-track-portfolios-from-cdsl-nsdl-cams-kfintech/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/casparser/cas-parser-track-portfolios-from-cdsl-nsdl-cams-kfintech/revisions/fa7d3aae2ab9/schema)