---
title: "Connect a custom domain"
method: POST
path: "/lists/{listId}/site-domain"
tags: ["Site Domain"]
---

# Connect a custom domain

`POST /lists/{listId}/site-domain`

## Request

- Base URL: `https://api.tinysend.com/v1`
- URL: `https://api.tinysend.com/v1/lists/{listId}/site-domain`
- Auth: HTTP bearer

Subdomains (news.acme.com) need one CNAME. Naked domains (acme.com) also get a TXT record for the security certificate and need ALIAS/flattened-CNAME support at the DNS provider; set www_enabled to serve www too.

## Path parameters

- `listId` string, required

## Request body

- object
  - `domain` string, required: domain or subdomain you own
  - `www_enabled` boolean: also serve www.<domain> (for naked domains)

## Response `201`

Domain added, records returned

- SiteDomainInfo
  - `domain` string, nullable, required
  - `default_url` string, required
  - `live_url` string, nullable, required
  - `status` 'not_configured' | 'pending' | 'active' | 'failed', required
  - `records` DnsRecordView[], required
    - `type` string, required
    - `name` string, required
    - `value` string, required
    - `found` boolean, required: whether we can see this record in DNS yet
    - `purpose` string: plain-words explanation of what the record does
  - `next_step` string, required: plain-language description of what happens next / what the user needs to do

## Other responses

- `422`: Validation error

---

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