Domains

Add a link domain

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.

post/v1/link-domains

Request

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

Request body

hostnamestring required

A subdomain of one of your verified sending domains. One link domain per sending domain.

Example request

{
  "hostname": "links.example.com"
}

Response

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

objectstring required
idstring required
hostnamestring required
domain_idstring nullable required

The sending domain the hostname sits under.

domainstring 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_statusstring nullable required

The certificate status Cloudflare reports, for troubleshooting.

last_errorstring nullable required

Why the link domain is not active yet, when Cloudflare says.

verified_atstring date-time nullable required

When it first became active.

last_checked_atstring date-time nullable required
created_atstring date-time required

Example response

{
  "object": "link_domain",
  "id": "cmlink123",
  "hostname": "links.example.com",
  "domain": "example.com",
  "ssl_status": "pending_validation",
  "dns_records": [
    {
      "type": "CNAME",
      "name": "links.example.com",
      "value": "links.smtpfa.st",
      "ttl": "Auto",
      "purpose": "Points the link domain at SMTPfast"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.