---
title: "Declare an existing mailbox connection on a BYO domain."
method: POST
path: "/byo-domains/{id}/connect-mailbox"
tags: ["byo-domains"]
---

# Declare an existing mailbox connection on a BYO domain.

`POST /byo-domains/{id}/connect-mailbox`

## Request

- Base URL: `https://api.coldrig.dev`
- URL: `https://api.coldrig.dev/byo-domains/{id}/connect-mailbox`
- Auth: HTTP bearer

Bypasses vendor setup entirely: the caller already holds the OAuth refresh token or SMTP+IMAP app password for a mailbox that already exists. This declares the mailbox the caller is connecting — it is not a claim about this platform's own outbound send transport.

## Path parameters

- `id` string, required

## Request body

- ConnectByoMailboxInput
  - `email` string, email, required
  - `transport` union, required: The mailbox connection the caller already holds — declares an EXISTING credential the caller supplies, not an OAuth flow this API initiates. This describes the mailbox being connected; it is not a claim about this platform's own outbound send transport.
    - ConnectByoMailboxSmtpInput
      - `kind` 'smtp', required
      - `host` string, required
      - `port` integer, required
      - `secure` boolean, required
      - `user` string, required
      - `pass` string, required
    - ConnectByoMailboxGmailInput
      - `kind` 'gmail_api', required
      - `clientId` string, required
      - `clientSecret` string, required
      - `refreshToken` string, required
    - ConnectByoMailboxGraphInput
      - `kind` 'ms_graph', required
      - `mode` 'delegated' | 'app_only', required
      - `tenantId` string, required
      - `clientId` string, required
      - `clientSecret` string, required
      - `refreshToken` string: Optional for app_only mode.

## Response `201`

Mailbox connection recorded.

- ConnectByoMailboxResult
  - `mailboxId` string, required
  - `email` string, required
  - `transportKind` string, required

## Other responses

- `400`: Request body failed schema validation.
- `401`: Missing, invalid, or inactive bearer token.
- `404`: Resource not found, or not owned by the authenticated account.

---

[API](https://skmtc.dev/coldrig/apis/agent-cold-email-api.md) · [All operations](https://skmtc.dev/coldrig/apis/agent-cold-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coldrig/apis/agent-cold-email-api/revisions/242a462d82c4?raw)