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

# Connect mailbox

`POST /workspaces/{workspaceID}/mailboxes`

## Request

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

Connect an SMTP/IMAP mailbox to the workspace. Send the outgoing server credentials under "smtp" and the incoming server credentials under "imap". Both are verified against the mail provider before anything is stored, so a bad host, port or password fails with 400 and creates nothing; the message names the failing protocol and, where the reason is recognized (wrong credentials, unreachable host, TLS mismatch, ...), a short cause. On success the mailbox is returned with status "pending": registration with the mail infrastructure finishes moments later and flips it to "active", or to "access_lost" if it fails. Poll GET /workspaces/{workspaceID}/mailboxes/{mailboxID} to observe the final status. Connecting is idempotent by address: a second request for an address already mid-connect returns 409 instead of racing the first. Google and Outlook mailboxes connect through /mailboxes/oauth-link instead.

## Path parameters

- `workspaceID` string, required

## Request body

- union
  - object
  - ApiCreateMailboxRequest
    - `address` string, required: Email address to send from.
    - `dailyEmailLimit` integer: Maximum emails this mailbox may send per day. Defaults to 30 when omitted.
    - `firstName` string, required: First name of the sender.
    - `imap` ApiMailboxConnectionRequest, required
      - `host` string, required: Hostname of the mail server.
      - `password` string, required: Password or provider-issued app password. Never returned by any endpoint.
      - `port` integer, required: Port the mail server listens on (for example 993 for IMAP, 465 or 587 for SMTP).
      - `username` string, required: Username used to authenticate with the mail server.
    - `lastName` string, required: Last name of the sender.
    - `signature` string: HTML signature appended to outgoing emails.
    - `smtp` ApiMailboxConnectionRequest, required
      - `host` string, required: Hostname of the mail server.
      - `password` string, required: Password or provider-issued app password. Never returned by any endpoint.
      - `port` integer, required: Port the mail server listens on (for example 993 for IMAP, 465 or 587 for SMTP).
      - `username` string, required: Username used to authenticate with the mail server.
    - `trackingDomain` string: Custom domain used for tracked links and open pixels.

## Response `201`

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'

## Other responses

- `400`: Bad Request
- `409`: Conflict
- `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)