API reference / Token auth

Domains

Register sending domains, publish DNS records, verify SPF/DKIM/DMARC alignment, and check domains against public blocklists.

GET /v1/domains

Token + X-MailStack-Org

List the organization’s sending domains.

Response

[ { "id": "...", "domain": "yourdomain.com", "status": 2, "dnsRecords": [ ... ] } ]

GET /v1/domains/{id}

Token + X-MailStack-Org

Get one domain with its full DNS record set.

Response

{ "id": "...", "domain": "yourdomain.com", "status": 1, "dnsRecords": [ ... ] }

POST /v1/domains

Token + X-MailStack-Org

Returns a Pending domain plus the DNS records (DKIM CNAME/TXT, SPF, DMARC) to publish in your zone. Domain status is integer-encoded: NotStarted=0, Pending=1, Verified=2, Failed=3.

Request body

{ "domain": "yourdomain.com", "mailFromSubdomain": "mail" }

Response

{
  "id": "3b1f...",
  "domain": "yourdomain.com",
  "status": 1,
  "customMailFromDomain": "mail.yourdomain.com",
  "dnsRecords": [
    { "type": "CNAME", "name": "ms1._domainkey.yourdomain.com", "value": "ms1.dkim.mailstack...", "ttl": 1800, "purpose": "DKIM" }
  ],
  "createdAt": "2026-06-18T10:00:00Z"
}

curl https://api.mailstack.voostack.com/v1/domains \
  -H "Authorization: Bearer <jwt>" \
  -H "X-MailStack-Org: org_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "yourdomain.com" }'

POST /v1/domains/{id}/verify

Token + X-MailStack-Org

Re-check DNS and flip to Verified once all records resolve.

Response

{ "id": "3b1f...", "status": 2, "verifiedAt": "2026-06-18T10:30:00Z" }

DELETE /v1/domains/{id}

Token + X-MailStack-Org

Remove a sending domain.

Response

{ "status": "ok" }

GET /v1/domains/{id}/blocklist

Token + X-MailStack-Org

Check the domain against public DNS blocklists.

Response

{ "domain": "yourdomain.com", "anyListed": false, "lists": [ { "provider": "Spamhaus", "zone": "dbl.spamhaus.org", "listed": false, "codes": [] } ] }

SDKs

Prefer a typed client? The Domains endpoints are covered by the official Node, .NET, Go, and Flutter/Dart SDKs.