---
title: "Connect Domain"
method: POST
path: "/domains/connect"
tags: ["Domains"]
---

# Connect Domain

`POST /domains/connect`

## Request

- Base URL: `https://api.supersend.io/v2`
- URL: `https://api.supersend.io/v2/domains/connect`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/supersend/apis/supersend-api/docs/domains/connect/post.ts> (a function with typed inputs; its response is checked against the schema)

Connects a domain the organization already owns (registered anywhere outside SuperSend) to a
team, so inboxes can be bought on it. Free. **Nothing changes at the registrar yet**: the
domain gets nameservers to set only once inboxes on it are paid for (list it in
`POST /setup/inbox-checkout`), and `POST /domains/{id}/verify` then shows them.

Use a domain only for outreach: changing its nameservers later moves all of its DNS (website,
other email) to SuperSend.

Connecting a domain that's already in the organization returns it with
`already_connected: true` (200) instead of failing.

## Request body

- object
  - `domain` string, required: Bare domain name; a URL or leading www. is stripped.
  - `team_id` string, uuid: Team to connect it to. Defaults to the caller's default team.

## Response `200`

Domain was already in the organization (`already_connected: true`)

- DomainSetupResponse
  - `success` boolean
  - `request_id` string
  - `data` DomainSetup
    - `object` string
    - `id` string, uuid
    - `name` string
    - `managed` 'internal' | 'external': internal = bought through SuperSend; external = connected (registered elsewhere)
    - `status` string
    - `team_id` string, uuid, nullable
    - `team` object, nullable
      - `id` string, uuid
      - `name` string
    - `stage` 'connected' | 'preparing_nameservers' | 'awaiting_nameservers' | 'ready' | 'setting_up' | 'unavailable'
    - `nameservers` object
      - `change_required` boolean: The owner must change the domain's nameservers to `set_to` at the registrar.
      - `set_to` string[], nullable
      - `current` string[], nullable: Nameservers last seen in DNS.
      - `verified` boolean
      - `verified_at` string, date-time, nullable
    - `mailboxes` object
      - `total` integer
      - `active` integer
      - `in_progress` integer
      - `failed` integer
      - `items` object[]
        - `email` string
        - `provider` 'google' | 'outlook' | 'azure' | 'smtp'
        - `status` 'pending' | 'processing' | 'active' | 'error'
    - `next` string: The one thing to do next, in plain words.
    - `already_connected` boolean: Connect only. The domain was already in the organization.
    - `check` object: Verify only.
      - `checked_at` string, date-time
      - `looked_up` boolean: Nameservers were looked up live in this call.
      - `error` string

## Other responses

- `201`: Domain connected
- `400`: Bad Request - Invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - Access denied
- `409`: The domain is in another SuperSend account (`domain_taken`) or another team in this organization (`domain_in_other_team`).

## Changes

- **2026-10-07** `b531caea83bd`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/supersend/apis/supersend-api/changes/domains/connect/post.md)

---

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