---
title: "Create mailbox OAuth link"
method: POST
path: "/workspaces/{workspaceID}/mailboxes/oauth-link"
tags: ["Mailboxes"]
---

# Create mailbox OAuth link

`POST /workspaces/{workspaceID}/mailboxes/oauth-link`

## Request

- Base URL: `https://api.salesforge.ai/public/v2`
- URL: `https://api.salesforge.ai/public/v2/workspaces/{workspaceID}/mailboxes/oauth-link`
- Auth: API key in header `Authorization`

Returns a Google or Outlook OAuth URL for connecting a mailbox. After the user authorizes, they are redirected to redirectUrl. redirectUrl must be pre-allowlisted — contact Salesforge support to add your URL. For Google, set oauthApp to "gmail_api" to authorize through the Google-verified app; omitted, the legacy app is used.

## Path parameters

- `workspaceID` string, required

## Request body

- ApiCreateMailboxOAuthLinkRequest
  - `email` string: Email address to pre-select on the provider consent screen.
  - `oauthApp` 'legacy' | 'gmail_api': Google OAuth app to authorize through; Google only, defaults to "legacy". "gmail_api" is the Google-verified app with narrower Gmail scopes. Mailboxes connected through it are not added to Warmforge automatically; connect them in Warmforge directly.
  - `provider` 'google' | 'outlook', required: Mail provider to connect: "google" or "outlook".
  - `redirectUrl` string, required: HTTPS URL the user is redirected to after OAuth authorization. Must be pre-allowlisted — contact Salesforge support to add your URL.

## Response `200`

OAuth authorization URL

- ApiMailboxOAuthLinkResponse
  - `url` string

## Other responses

- `400`: Bad Request
- `500`: Internal Server Error

---

[API](https://skmtc.dev/salesforge/apis/salesforge-api.md) - [All operations](https://skmtc.dev/salesforge/apis/salesforge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/salesforge/apis/salesforge-api/revisions/3f946278b378?raw)