Skip to main content
POST
Upgrade Sending Domain DNS
Start a one-time, optional upgrade of a sending domain to our new DNS structure. It is recommended: it improves deliverability and security, and Sequenzy can later change keys and sending infrastructure without you editing DNS again. The domain is not removed: it keeps sending on its current records while the upgrade is in progress, and sender profiles, sequences and tracking stay as they are. website.dnsUpgrade.status tells you whether a domain can start. The upgrade is being offered to domains gradually; until it reaches yours, status is unavailable. It is available for a verified domain on the previous record set (a DKIM TXT at sequenzy._domainkey and a send return path, for example), including older domains that only sent through Amazon SES. Such a domain needs a working DMARC record first: without one, this endpoint answers 400 with “Add a DMARC record for this domain before upgrading its DNS records.” and the status is unavailable. Domains that use Amazon’s three-CNAME DKIM records, and domains in the middle of an earlier records migration, are unavailable too. Every unavailable domain gets a 400 from this endpoint.

How it works

  1. Call this endpoint. The response lists four CNAMEs in website.dnsUpgrade.records.
  2. Publish them next to your current records. Remove nothing yet: your current records keep the domain verified and sending until the switch.
  3. Sequenzy checks the new records with each verification. Call Verify Sending Domain to check right away.
  4. About an hour after the required records (dkim and return_path) are visible on public DNS (Google and Cloudflare resolvers), the domain switches by itself. The wait lets cached “does not exist” answers expire; verifying checks right away but does not skip it. Sequenzy prepares the domain’s sending setup separately and switches only once it is confirmed, so sending is normally not interrupted and no emails are held. If that isn’t possible for a domain, emails sent through Amazon SES can be held for a few minutes while SES confirms the new setup, then they go out. Some domains get a new DKIM key during the upgrade; you still add the same four CNAMEs.
  5. website.dnsUpgrade.status becomes completed and oldRecords lists the records the domain no longer uses. Keep them until deleteOldRecordsAfter, 8 days after the switch; deleting them after that is optional. Before the switch, replacedRecords lists the same records. Each verification marks a record removed once it is gone from public DNS. For an older SES-only domain these include the old return path records (MX and TXT at send.mail.example.com) and the DKIM TXT; your DMARC record stays.
Publish all four, and set every CNAME to DNS only on Cloudflare. The values differ for each domain; always publish the ones returned. Once started, an upgrade can’t be cancelled: until the switch it changes nothing, and the domain keeps sending on its current records. This endpoint requires the websites:write scope. CLI: sequenzy websites upgrade-dns mail.example.com. MCP: upgrade_sending_domain_dns.

Request

string
required
Configured sending domain.
string
Return-path subdomain label for the new records, 1 to 63 characters. Defaults to rp; if rp is taken or already has DNS records, rp1, then sqrp. A label that already has DNS records, or is the current return path or the tracking domain label, is rejected with 400, and inbound is not allowed. The SES return path is this label followed by 2 (rp2 by default), moving to bounces or sesbounces if that name is in use. The body is optional.

Responses

object
status is in_progress, startedAt is set and records lists the CNAMEs to publish, each with purpose, type, name, value, required, status (pending, verified or misconfigured) and, when known, a diagnostic explaining why it is not verified yet.

After the switch

GET /api/v1/websites/{domain} then returns:
The new records now appear in website.dnsRecords.platformDnsRecords and website.bounceRecords. completed is shown for 30 days after the switch; after that, status is unavailable because the domain already uses the current records.