---
title: "List link domains"
method: GET
path: "/v1/link-domains"
tags: ["Domains"]
---

# List link domains

`GET /v1/link-domains`

## Request

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

The team's custom link domains with their status and DNS records. available says whether the feature is on, included_in_plan whether the team's plan has it. Not in Resend. Requires the domain:read scope.

## Response `200`

Link domains

- LinkDomainList
  - `object` string, required
  - `has_more` boolean, required
  - `data` LinkDomain[], required
    - `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
  - `available` boolean, required: Whether custom link domains are available on this server. When false, creating one answers 503.
  - `included_in_plan` boolean, required: Whether the team's plan includes custom link domains (every paid plan). When false, creating one answers 403 and mail uses smtpfa.st links, also through a link domain added earlier.

## Other responses

- `401`: Invalid or missing API key
- `403`: Forbidden - domain not verified or insufficient permissions
- `429`: Rate limit exceeded - retry after the period indicated in the Retry-After header
- `500`: Internal server 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)