---
title: "Connect a domain to a hosting or email provider"
method: POST
path: "/api/domains/{domain}/connect"
tags: ["Connect"]
---

# Connect a domain to a hosting or email provider

`POST /api/domains/{domain}/connect`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/domains/{domain}/connect`
- Auth: HTTP bearer

Connects a domain to a hosting or email provider by auto-detecting the provider from a target URL or accepting an explicit provider name.

For domains managed through the platform, DNS records are set automatically (status: `dns_set`). For imported domains (external registrar), returns the records as instructions to add manually at your registrar (status: `manual_setup_required`, records have status `pending`).

Supported hosting providers: vercel, netlify, cloudflare-pages, github-pages, railway, fly.
Supported email providers: google-workspace, fastmail, proton.

Use `GET /api/domains/{domain}/connect` to list all available providers and methods.

Mail routing: a change to where the domain's mail is delivered (its MX or NS records, the address records an MX host inside the zone resolves through, or those of a host that receives Domani mail and publishes no MX) needs the `email:auth_secrets` scope, since whoever receives the mail receives its sign-in codes. Without it the request answers 403 INSUFFICIENT_SCOPE before anything changes, and a token confined to mailboxes answers 403 MAILBOX_CONFINED even with it. Other records need only `domains:write`. Every routing change is recorded in the audit log.

## Path parameters

- `domain` string, required

## Request body

- object
  - `target` string: Target URL for auto-detection (e.g. my-app.vercel.app)
  - `provider` string: Explicit provider name (e.g. vercel, google-workspace)
  - `method` string: Connection method if provider has multiple (e.g. cname-only)
  - `dry_run` boolean: Preview only: returns the diff (create/replace/already_set/keep) without writing anything.
  - `confirm_replace_mx` boolean: Required when the connect would replace existing MX records pointing at another provider (409 MX_REPLACEMENT_REQUIRES_CONFIRMATION otherwise) - it reroutes the domain's email.

## Response `200`

Domain connected or DNS instructions returned

- object
  - `domain` string
  - `provider` string
  - `category` 'hosting' | 'email'
  - `method` string
  - `records` DnsRecord[]
    - `type` 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT' | 'NS' | 'SRV' | 'CAA' | 'TLSA', required: DNS record type. TLSA publishes a DANE record; its value is the rdata 'usage selector matching-type hex-data'.
    - `name` string, required: Record name (@ for root, or subdomain, e.g. _443._tcp for TLSA)
    - `value` string, required: Record value (IP address, hostname, or TLSA rdata like '3 1 1 abc123...')
    - `ttl` integer, required: Time to live in seconds
    - `priority` integer: Priority value (required for MX records)
    - `required` boolean: False when the zone Domani manages for the domain cannot hold the record (a TXT longer than the registrar accepts); such a record is shown but not needed for mail to work. Absent on plain zone records.
  - `docs` string, uri
  - `status` 'dns_set' | 'manual_setup_required' | 'dry_run': dns_set = records written automatically. manual_setup_required = imported domain, add records at your registrar. dry_run = preview only, nothing written.
  - `hint` string
  - `next_steps` string[]: Provider-specific actions to complete after DNS records are set
  - `diff` object: Dry run only: what the write would do - create, replace (existing records that would be removed), already_set, keep (untouched rrsets).

## Other responses

- `400`: Invalid request parameters
- `401`: Missing or invalid API key
- `403`: Moving the domain's mail needs the email:auth_secrets scope (INSUFFICIENT_SCOPE) and a token not confined to mailboxes (MAILBOX_CONFINED)
- `404`: Domain not found
- `429`: Rate limit exceeded - wait and retry

---

[API](https://skmtc.dev/domani/apis/domani-run-api.md) · [All operations](https://skmtc.dev/domani/apis/domani-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domani/apis/domani-run-api/revisions/7679f8159533?raw)