Custom OAuth

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

{
  "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

At least one of google or microsoft sections must be present.

If the Google section is provided:

appName and clientId are mandatory.

Each mailboxesPerDomain must:

Be an object where keys are domain IDs.

Contain an array of mailbox entries.

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 <CLIENT_ID>: expected <APP>, got <PROVIDER_APP>` `Validation failed for client ID <CLIENT_ID>: <provider error>`
404 Not Found	Google only: No admin mailbox is available on a domain that needs client ID addition	`Admin mailbox not found for domain <DOMAIN_ID>`
429 Too Many Requests	Per-mailbox rate limit exceeded (3 in 7 days)	`Rate limit exceeded for mailbox '<MAILBOX_ID>'\n Limit is 3 requests per 7 days`
422 Unprocessable Entity	Request body fails schema validation (see Validation Rules)	e.g. `google.mailboxesPerDomain.<domain>[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 '<MAILBOX_ID>'\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.

curl --location --request POST 'https://api.zapmail.ai/api/v2/mailboxes/custom-oauth' \ --header 'x-auth-zapmail;' \ --header 'Content-Type: application/json' \ --data-raw '{ "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" } ] } } }'

Description#

Request Body#

Structure Overview#

Field Details#

Validation Rules#

Rate Limiting#

Usage Notes#

Request