Link domain
The domain your unsubscribe and tracking links use. 5 endpoints, each also a tool for your AI through MCP. Authentication and errors are on the overview.
Get the link domain
GET/api/v1/link-domain
The hostname that carries unsubscribe, click and open links in this workspace's emails, the CNAME record to add, and whether DNS and the certificate are ready.
MCP tool get_link_domainRead-only
Returns
hostnamerequiredstring | null- The workspace's link domain, null when none is set
statusrequired"none" | "pending_dns" | "pending_tls" | "active" | "failed"- active = links in emails use it
dnsrequired"ok" | "missing" | "wrong" | "unknown"- What our resolver sees at the hostname
tlsrequired"active" | "pending" | "failed" | "none"- Certificate on Cloudflare
messagerequiredstring | null- What to do next, null when active
recordrequiredobject | null- The DNS record to add
suggestionrequiredstring | null- links.<sending domain> when nothing is set yet
requiredrequiredboolean- Campaigns can't launch without an active link domain on this server
verifiedAtrequiredstring | nullcheckedAtrequiredstring | null
curl https://ballast.to/api/v1/link-domain \
-H "Authorization: Bearer $BALLAST_API_KEY"Set the link domain
PUT/api/v1/link-domain
Sets the subdomain (e.g. links.acme.com) that carries the links in this workspace's emails. Add the returned CNAME record at your DNS provider; we issue the certificate and switch it on once both are ready. Replacing an active one breaks the unsubscribe links in emails already sent, so it needs replace: true.
MCP tool set_link_domainOwners and admins
Parameters
hostnamerequiredstring- A subdomain of a domain you own, e.g. links.acme.com
replaceboolean- Confirm replacing an active link domain
Returns the same fields as Get the link domain.
curl -X PUT https://ballast.to/api/v1/link-domain \
-H "Authorization: Bearer $BALLAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"hostname":"<hostname>"}'Check the link domain now
POST/api/v1/link-domain/check
Looks up the CNAME and asks Cloudflare for the certificate again. The worker also checks every minute for the first hour.
MCP tool check_link_domain
Returns the same fields as Get the link domain.
curl -X POST https://ballast.to/api/v1/link-domain/check \
-H "Authorization: Bearer $BALLAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Remove the link domain
DELETE/api/v1/link-domain
Unsubscribe and tracked links in emails already sent stop working, and campaigns can't send until a new one is active.
MCP tool remove_link_domainOwners and adminsMCP asks to confirm
Returns
okrequiredtrue
curl -X DELETE https://ballast.to/api/v1/link-domain \
-H "Authorization: Bearer $BALLAST_API_KEY"Check a link domain CNAME
GET/api/v1/check/link
Whether links.<domain> has the CNAME to our link target. DNS only.
MCP tool check_link_cnameRead-only
Parameters
domainrequiredquery · string
Returns
hostnamerequiredstringtargetrequiredstring | nulldnsrequired"ok" | "missing" | "wrong" | "unknown"
curl https://ballast.to/api/v1/check/link?domain=<domain> \
-H "Authorization: Bearer $BALLAST_API_KEY"