Transactional domains

Before you start

• The root domain must already be verified in Shipmail. List yours with GET /v1/domains.
• Writes need domains:write, and the key must act for an Owner or Admin with access to every mailbox.
• A key limited to some domains reaches only the subdomains of those domains. A key limited to mailboxes reaches none.
• Setup steps have their own limits per key: 20 creates and 20 deletes per hour, and 120 checks per 10 minutes. Past them the API answers 429.

The transactional domain object

{
  "object": "transactional_domain",
  "id": "txdom_0123456789abcdefghjkmnpq",
  "name": "mail.example.com",
  "root_domain": "example.com",
  "status": "pending",
  "mail_from_domain": "mail.mail.example.com",
  "dns_records": [
    {
      "key": "dkim",
      "type": "TXT",
      "host": "shipmail._domainkey.mail.example.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqh...",
      "priority": null,
      "ttl": 300,
      "description": "Signs your transactional email so inboxes trust it.",
      "status": "pending"
    }
  ],
  "verified_at": null,
  "created_at": "2026-11-08T09:00:00.000Z"
}

dns_records has three entries: the DKIM key (dkim), and the MX and SPF records of the return path (mail_from_mx and mail_from_spf). Publish each one exactly as returned. The transactional email guide explains what each record does.

List transactional domains

Returns { "object": "list", "data": [...] } with every sending subdomain the key can reach, without pagination.

Create a transactional domain

{
  "root_domain": "example.com",
  "subdomain": "mail"
}

root_domain is a verified domain of your organization. subdomain is one DNS label: mail gives mail.example.com. Returns 201 with the domain and the DNS records to publish.

If setup stops part way, the domain comes back with an empty dns_records, or the request fails with transactional_domain_setup_failed. Send the same request again: it resumes the setup instead of creating a second domain.

Retrieve a transactional domain

Returns the domain with the status Shipmail last recorded. Shipmail also checks pending domains in the background.

Verify a transactional domain

Checks the DNS records now and returns the domain with the status of each record. Once every record is verified, status becomes verified and you can create senders on it. DNS usually updates in a few minutes, sometimes up to an hour. The verification tier allows 1 request per minute, so poll no faster than that.

Delete a transactional domain

Returns 204. Shipmail stops sending from the subdomain and deletes its DKIM key; you can then delete its DNS records. Deleting is refused with 409 while senders use the subdomain. If removal stops part way, send the same request again.

Errors

Errors use the standard error envelope. Branch on details[0].code, not on the message.