---
title: "Reconnect mailbox"
method: POST
path: "/workspaces/{workspaceID}/mailboxes/{mailboxID}/reconnect"
tags: ["Mailboxes"]
---

# Reconnect mailbox

`POST /workspaces/{workspaceID}/mailboxes/{mailboxID}/reconnect`

## Request

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

Requests reconnection of a mailbox that has lost access. Branch on the response `result` field (not mailbox.status alone).

Results:
- reconnected: credentials verified; mailbox is active again. nextStep: nothing to do.
- already_connected: mailbox was already active. nextStep: nothing to do.
- disconnected: still access_lost after an SMTP/IMAP check. nextStep: PATCH .../connection-settings, then retry reconnect. If the provider account is missing, send both SMTP and IMAP so it is registered again.
- oauth_required: Google/Outlook needs user consent. nextStep: open oauthUrl, then handle redirectUrl. redirectUrl is required and must be allowlisted (contact Salesforge support).
- suspended: admin/billing suspension. nextStep: contact support.
- deleted: mailbox is deleted. nextStep: connect again as a new mailbox.
- pending: connection still being set up. nextStep: wait and poll GET mailbox.
- ineligible: reconnect does not apply for this state.

redirectUrl: required for Google/Outlook OAuth mailboxes; omit for SMTP/IMAP. Same allowlisting rules as POST /mailboxes/oauth-link.

## Path parameters

- `workspaceID` string, required
- `mailboxID` string, required

## Request body

- union
  - object
  - ApiReconnectMailboxRequest
    - `redirectUrl` string: HTTPS URL the user is redirected to after OAuth re-authorization. Required for Google and Outlook mailboxes; omit for SMTP/IMAP. Must be pre-allowlisted — contact Salesforge support to add your URL.

## Response `200`

Reconnect outcome

- ApiReconnectMailboxResponse
  - `mailbox` ApiMailboxResponse
    - `address` string
    - `dailyEmailLimit` integer
    - `disconnectReason` string
    - `firstName` string
    - `id` string
    - `lastName` string
    - `mailboxProvider` 'gmail' | 'outlook' | 'smtp'
    - `resolvedSignature` string
    - `signature` string
    - `status` 'active' | 'frozen' | 'access_lost' | 'deleted' | 'inactive' | 'pending' | 'suspended'
    - `trackingDomain` string
    - `trackingDomainStatus` 'active' | 'pending'
  - `message` string: Short explanation of the outcome.
  - `nextStep` string: What the caller should do next.
  - `oauthUrl` string: OAuth authorization URL. Present only when result is oauth_required.
  - `result` 'reconnected' | 'already_connected' | 'disconnected' | 'oauth_required' | 'suspended' | 'deleted' | 'pending' | 'ineligible': Explicit reconnect outcome. Prefer this over combining fields with mailbox.status.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Mailbox not found
- `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)