Domains

Add, verify, and manage sending domains for your workspace.

Setup Flow

Sending domains require DNS verification before they can be used. Follow these four steps to add and verify a domain:

POST /domains with your domain name — the response includes the DNS records you need to add.
Add DNS records at your domain provider (DKIM CNAMEs + verification TXT record).
POST /domains/:id/verify to check if the domain is ready. DNS propagation can take up to 48 hours, so you may need to retry.
Once verified, set from_email to an address on that domain when sending emails.

GET

/domains

List all sending domains in your workspace.

curl "https://api.topmail.so/api/v1/domains" \
  -H "Authorization: Bearer tm_live_abc123"

POST

/domains

Add a new sending domain. Returns the DNS records required for verification.

Request Body

Name	Type	Required	Description
domain	string	Required	The domain to verify (e.g., "mybrand.com").

curl -X POST https://api.topmail.so/api/v1/domains \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mybrand.com"
  }'

GET

/domains/:id

Retrieve a single domain with its verification status and DNS records.

curl https://api.topmail.so/api/v1/domains/DOMAIN_ID \
  -H "Authorization: Bearer tm_live_abc123"

POST

/domains/:id/verify

Check the verification status of a domain. Call this after the user has added DNS records at their provider.

curl -X POST https://api.topmail.so/api/v1/domains/DOMAIN_ID/verify \
  -H "Authorization: Bearer tm_live_abc123"

DELETE

/domains/:id

Remove a sending domain from your workspace.

curl -X DELETE https://api.topmail.so/api/v1/domains/DOMAIN_ID \
  -H "Authorization: Bearer tm_live_abc123"