---
title: "Add a link domain"
method: POST
path: "/v1/link-domains"
tags: ["Domains"]
---

# Add a link domain

`POST /v1/link-domains`

## Request

- Base URL: `https://smtpfa.st/api`
- URL: `https://smtpfa.st/api/v1/link-domains`
- Auth: HTTP bearer

Add a custom hostname for tracking and unsubscribe links, such as links.example.com. It must be a subdomain of one of your verified sending domains, one per sending domain. Publish the CNAME record from dns_records; the link domain turns active once Cloudflare sees it and issues a certificate, usually within minutes. Paid plans only: 403 with code plan_upgrade_required on the free plan. 422 when the hostname is not under a verified sending domain, 409 when that domain already has one, 503 with code link_domains_unavailable when the feature is off. Not in Resend. Requires the domain:write scope and an owner or admin; 5 per hour per team.

## Request body

- CreateLinkDomainRequest
  - `hostname` string, required: A subdomain of one of your verified sending domains. One link domain per sending domain.

## Response `201`

The link domain, pending until the CNAME record is in place

- LinkDomain: A custom hostname for open tracking, click tracking and unsubscribe links. While it is active, email whose From address is on the same registrable domain uses it instead of smtpfa.st, in the body and in the List-Unsubscribe header.
  - `object` string, required
  - `id` string, required
  - `hostname` string, required
  - `domain_id` string, nullable, required: The sending domain the hostname sits under.
  - `domain` string, nullable, required
  - `status` 'pending' | 'active' | 'failed', required: pending until Cloudflare sees the CNAME record and issues the certificate, then active. failed means it will not become active without a change on your side (last_error says why); fix it and refresh. Mail uses the link domain only while it is active.
  - `ssl_status` string, nullable, required: The certificate status Cloudflare reports, for troubleshooting.
  - `last_error` string, nullable, required: Why the link domain is not active yet, when Cloudflare says.
  - `dns_records` LinkDomainDnsRecord[], required
    - `type` 'CNAME' | 'TXT', required
    - `name` string, required
    - `value` string, required
    - `ttl` string, required
    - `purpose` string, required
    - `required` boolean, required: The CNAME is required. A TXT record Cloudflare offers is optional: it lets the hostname activate before the CNAME is live.
    - `status` 'pending' | 'verified' | 'not_needed', required: pending while the link domain is not active. Once it is active the CNAME is verified (keep it: certificate renewals need it) and a TXT record is not_needed, so you can remove it.
  - `verified_at` string, date-time, nullable, required: When it first became active.
  - `last_checked_at` string, date-time, nullable, required
  - `created_at` string, date-time, required

## Other responses

- `400`: Bad request - check your payload
- `401`: Invalid or missing API key
- `403`: Forbidden - domain not verified or insufficient permissions
- `409`: Conflict - the resource already exists or changed meanwhile
- `422`: The request is well formed but cannot be carried out in the current state, for example an unpublished template
- `429`: Rate limit exceeded - retry after the period indicated in the Retry-After header
- `500`: Internal server error
- `502`: Error
- `503`: Error

---

[API](https://skmtc.dev/smtpfa/apis/smtpfast-api.md) · [All operations](https://skmtc.dev/smtpfa/apis/smtpfast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smtpfa/apis/smtpfast-api/revisions/79dda742f53e?raw)