---
title: "Refresh a link domain's status"
method: POST
path: "/v1/link-domains/{id}/refresh"
tags: ["Domains"]
---

# Refresh a link domain's status

`POST /v1/link-domains/{id}/refresh`

## Request

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

Ask Cloudflare for the current state now, instead of waiting for the automatic check (every few minutes while pending, daily once active). Also restarts automatic checks for a failed link domain. Not in Resend. Requires the domain:write scope; 30 per 10 minutes per team.

## Path parameters

- `id` string, required

## Response `200`

The link domain with its current status

- 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

- `401`: Invalid or missing API key
- `403`: Forbidden - domain not verified or insufficient permissions
- `404`: Resource not found
- `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)