# Custom OAuth ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /v2/mailboxes/custom-oauth: post: summary: Custom OAuth deprecated: false description: >- ### **Description** This endpoint allows users to connect their **Google** or **Microsoft** mailboxes to your application using **OAuth authorization links** provided for each mailbox. Each mailbox must include a valid OAuth link and a unique mailbox ID (UUID). The endpoint validates the structure, UUIDs, and URLs before initiating the connection. --- ### **Request Body** #### **Structure Overview** ```json { "google": { "appName": "string (required if google section is present)", "clientId": "string (required if google section is present)", "mailboxesPerDomain": { "domainId": [ { "mailboxId": "string (UUID)", "oauthLink": "string (URL)" } ] } }, "microsoft": { "mailboxesPerDomain": { "domainId": [ { "mailboxId": "string (UUID)", "oauthLink": "string (URL)" } ] } } } ``` --- ### **Field Details** | Field | Type | Required | Description | |-------|------|-----------|-------------| | **google** | object | Optional | Contains configuration and OAuth links for Google mailboxes. | | **google.appName** | string | Required (if `google` is provided) | Name of the Google application. | | **google.clientId** | string | Required (if `google` is provided) | Client ID of the Google OAuth app. | | **google.mailboxesPerDomain** | object | Required (if `google` is provided) | Key-value map of domain IDs and mailbox entries. | | **microsoft** | object | Optional | Contains configuration and OAuth links for Microsoft mailboxes. | | **microsoft.mailboxesPerDomain** | object | Required (if `microsoft` is provided) | Key-value map of domain IDs and mailbox entries. | | **mailboxId** | string (UUID) | Required | Unique identifier for the mailbox. Must be a valid UUID. | | **oauthLink** | string (URL) | Required | Valid OAuth authorization link for the mailbox. | --- ### **Validation Rules** 1. **At least one** of `google` or `microsoft` sections must be present. 2. If the **Google** section is provided: - `appName` and `clientId` are **mandatory**. 3. Each `mailboxesPerDomain` must: - Be an **object** where keys are domain IDs. - Contain an **array** of mailbox entries. 4. Each mailbox entry must: - Include a **valid UUID** as `mailboxId`. - Include a **valid URL** as `oauthLink`. --- | HTTP Status | When it Happens | Example Message | |---|---|---| | **400 Bad Request** | One or more requested `mailboxId`s are not found for the authenticated user, or do not match the user’s `serviceProvider` or workspace; or Google client/app validation mismatch | `Some mailboxes not found`
`App name mismatch for client ID : expected , got `
`Validation failed for client ID : ` | | **404 Not Found** | Google only: No admin mailbox is available on a domain that needs client ID addition | `Admin mailbox not found for domain ` | | **429 Too Many Requests** | Per-mailbox rate limit exceeded (3 in 7 days) | `Rate limit exceeded for mailbox ''\n Limit is 3 requests per 7 days` | | **422 Unprocessable Entity** | Request body fails schema validation (see Validation Rules) | e.g. `google.mailboxesPerDomain.[0].mailboxId must be a valid UUID`
`At least one of 'google' or 'microsoft' sections must be provided` | ## **Rate Limiting** This endpoint applies a **per-mailbox** rate limit to prevent abuse. - **Rule:** Up to **3 requests per mailbox** in a **7-day** window. - **Scope:** The limit is applied per **Mailbox**, not by user or domain. **On limit breach** - **Status:** `429 Too Many Requests` - **Message:** `Rate limit exceeded for mailbox ''\n Limit is 3 requests per 7 days` ### **Usage Notes** - `oauthLink` should be generated dynamically per mailbox from the provider’s OAuth flow. - Valid client id and app name must be given, same as your platform's Google Cloud project. - Only mailboxes that are `ACTIVE`, belong to the authenticated `userId` and `workspaceId` and have `disableReason = null` can be processed. - If any mailbox in the batch fails prechecks (ownership, status, workspace, provider), the request fails with `400 Bad Request: Some mailboxes not found`. tags: - mailbox parameters: - name: x-auth-zapmail in: header description: '' required: true example: '' schema: type: string - name: x-workspace-key in: header description: '' required: false example: '' schema: type: string - name: ' x-service-provider' in: header description: '' required: false example: '' schema: type: string requestBody: content: application/json: schema: type: object properties: google: type: object properties: appName: type: string clientId: type: string mailboxesPerDomain: type: object properties: domainId: type: array items: type: object properties: mailboxId: type: string oauthLink: type: string required: - mailboxId - oauthLink x-apidog-orders: - mailboxId - oauthLink required: - domainId x-apidog-orders: - domainId required: - appName - clientId - mailboxesPerDomain x-apidog-orders: - appName - clientId - mailboxesPerDomain microsoft: type: object properties: mailboxesPerDomain: type: object properties: domainId: type: array items: type: object properties: mailboxId: type: string oauthLink: type: string x-apidog-orders: - mailboxId - oauthLink required: - mailboxId - oauthLink required: - domainId x-apidog-orders: - domainId required: - mailboxesPerDomain x-apidog-orders: - mailboxesPerDomain x-apidog-orders: - google - microsoft example: google: appName: ColdStats clientId: 1234567890-abcdefg1234567890.apps.googleusercontent.com mailboxesPerDomain: d91b34a0-67e9-4a3f-b1a8-31f8b6f7f001: - mailboxId: a12c4b23-91f3-4b7b-8ad9-9876fcb23456 oauthLink: >- https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&client_id=1234567890-abcdefg1234567890.apps.googleusercontent.com&prompt=consent&redirect_uri=https%3A%2F%2Fapp.coldstats.ai%2Fauth%2Fgoogle%2Fcallback&response_type=code&scope=https%3A%2F%2Fmail.google.com%2F+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile&state=9e5f124d-3e2b-4b09-8d3e-15a7e42db4a7 - mailboxId: b34f56e7-12cd-4e8a-9a67-8abf95acdef0 oauthLink: >- https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&client_id=1234567890-abcdefg1234567890.apps.googleusercontent.com&prompt=consent&redirect_uri=https%3A%2F%2Fapp.coldstats.ai%2Fauth%2Fgoogle%2Fcallback&response_type=code&scope=https%3A%2F%2Fmail.google.com%2F&state=75a92c9b-2e7c-4968-bf9f-5e12c4dc9054 microsoft: mailboxesPerDomain: a45e91b7-36c2-4b91-91a4-56d3d0b87612: - mailboxId: c67e21a1-7e43-4a1b-a25a-97a23d5e3a11 oauthLink: >- https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=8c7f1b3f-9c1e-4aab-b6f8-fb01c1234567&response_type=code&redirect_uri=https%3A%2F%2Fapp.coldstats.ai%2Fauth%2Fmicrosoft%2Fcallback&response_mode=query&scope=Mail.Read+Mail.Send+offline_access+openid+profile&state=ee67c1ad-2e76-4870-b4a3-0a54a1c9a3b2 responses: '200': description: '' content: application/json: schema: type: object properties: status: type: integer message: type: string data: type: object properties: exportId: type: integer required: - exportId x-apidog-orders: - exportId required: - status - message - data x-apidog-orders: - status - message - data headers: {} x-apidog-name: Success '400': description: '' content: application/json: schema: type: object properties: status: type: integer message: type: string errorId: type: string required: - status - message - errorId headers: {} x-apidog-name: Bad Request '422': description: '' content: application/json: schema: type: object properties: status: type: integer message: type: string errorId: type: string required: - status - message - errorId x-apidog-orders: - status - message - errorId headers: {} x-apidog-name: Validation security: [] x-apidog-folder: mailbox x-apidog-status: released x-run-in-apidog: https://app.apidog.com/web/project/797058/apis/api-23834066-run components: schemas: {} securitySchemes: {} servers: - url: https://api.zapmail.ai/api description: Prod Env security: [] ```