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

# Connect Email Provider (Initiate OAuth)

`POST /v4/inbox/connect`

## Request

- Base URL: `https://api.casparser.in`
- URL: `https://api.casparser.in/v4/inbox/connect`
- Auth: API key in header `x-api-key`

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
  - `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)
  - `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.

## Response `200`

OAuth URL generated successfully

- object
  - `status` string
  - `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
  - `expires_in` integer: Seconds until the OAuth URL expires (typically 10 minutes)

## Other responses

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

## Changes

- **2026-09-13** `cf1b57c0f2f7`: 1 warning
  - the optional response header `X-Request-ID` removed for the status `401`
- **2026-08-15** `fa7d3aae2ab9`: 1 warning, 1 info
  - added the new `zoho` enum value to the `provider` response property for the response status `200`
  - added the new `zoho` enum value to the request property `provider`
- **2026-08-15** `e7bc94a9fee1`: 1 breaking, 1 info
  - removed the enum value `zoho` of the request property `provider`
  - removed the `zoho` enum value from the `provider` response property for the response status `200`
- **2026-08-09** `c9918aebb2de`: 2 info
  - added the new optional request property `provider`
  - added the optional property `provider` to the response with the `200` status
- **2026-07-12** `c74b9ecd5b53`: 1 warning
  - added the new `failed` enum value to the `status` response property for the response status `401`

[Operation history](https://skmtc.dev/casparser/apis/cas-parser-track-portfolios-from-cdsl-nsdl-cams-kfintech-2/changes/v4/inbox/connect/post.md)

---

[API](https://skmtc.dev/casparser/apis/cas-parser-track-portfolios-from-cdsl-nsdl-cams-kfintech-2.md) - [All operations](https://skmtc.dev/casparser/apis/cas-parser-track-portfolios-from-cdsl-nsdl-cams-kfintech-2/llms.txt) - [OpenAPI document](https://skmtc.dev/casparser/apis/cas-parser-track-portfolios-from-cdsl-nsdl-cams-kfintech-2/revisions/9d8f1445bad3?raw)
