Buttondown SPF and DKIM setup

What you are setting up

Buttondown is a newsletter service, and by default it sends every issue from its own domain, buttondown.email. A custom sending domain moves the From address, the DKIM signature, and the return path onto a domain you own, so the reputation you build travels with you. Buttondown separates this from a custom hosting domain (your archive and subscribe pages on the web). Hosting needs a paid plan; sending from your own domain is available on every plan, including the free one, and Buttondown requires it if you import more than 10,000 subscribers from another service. Buttondown does not run its own mail servers. Its docs describe shifting traffic across “email-sending partners,” name Postmark as the only partner behind the manual setup, and its SPF troubleshooting example uses a Mailgun include, so the records that end up under your subdomain are the partners', generated and maintained by Buttondown.

Publish SPF and DKIM

In Buttondown, go to Settings > Sending domain and add the domain you will send from. What Buttondown shows next depends on what you typed. Enter a subdomain (Buttondown recommends mail.example.com or newsletter.example.com) and you get the managed setup: two NS records that delegate that subdomain to Buttondown's nameservers. Enter your root domain (example.com) and the managed option does not appear at all; you get the manual records instead, which you can also choose for a subdomain by switching to the manual version of the list. The managed shape is:

Type:  NS
Host:  mail            (just the label; your DNS host appends example.com)
Value: (the first nameserver Buttondown shows in Settings)

Type:  NS
Host:  mail
Value: (the second nameserver Buttondown shows in Settings)

That is the whole list. Once the delegation resolves, Buttondown publishes the DKIM keys, the SPF record for the return path, and the tracking-domain CNAME inside mail.example.com itself, and it can add or swap sending partners later without asking you to touch DNS again. The two nameserver values are shown only in your Settings page, so copy them from there. Buttondown's Cloudflare and Namecheap guides both stress that the Host field takes only the label: mail, not mail.example.com, which Namecheap would turn into mail.example.com.example.com. If your registrar cannot create NS records at all, Buttondown's advice is to move DNS to a host that can (it names Cloudflare and deSEC).

The manual records are a set of CNAME and TXT records shown in the same place, and Buttondown states that manual setups are currently supported on Postmark only, so the shape is Postmark's: a DKIM TXT at a _domainkey host and a return-path CNAME, exactly as covered in our Postmark guide. Add each one exactly as shown. On Cloudflare, every CNAME must be DNS only (gray cloud), not Proxied; a proxied CNAME is the single most common reason Buttondown records fail to validate. Manual mode also means you own the subdomain's MX records, so reply tracking is off by default and replies land straight in your inbox; it can be turned on under Settings > Sending domain > Add-ons, which is also where a manual setup adds the optional click-tracking CNAME (a managed setup gets it automatically). Then return to Buttondown and click Check records. Cloudflare usually applies changes within a minute or two, Namecheap in about half an hour.

Add DMARC

Buttondown publishes SPF and DKIM for you but leaves DMARC to you, and the record belongs at your root domain, where it covers mail.example.com and every other subdomain you send from:

Type:  TXT
Host:  _dmarc
Value: v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com

Your From is @mail.example.com, and the DKIM d= and the Return-Path domain both sit under that same subdomain, so alignment holds under DMARC's default relaxed mode with the record at the root. One thing to check before you rely on that: a receiver looks for _dmarc.mail.example.com first and only falls back to _dmarc.example.com when nothing is there. With the managed setup, _dmarc.mail.example.com lives inside the zone you delegated to Buttondown, so if a record ever appears there it is Buttondown's, not yours, and it takes precedence for Buttondown mail. Query that name once after delegation (dig TXT _dmarc.mail.example.com) so you know which policy actually applies. Build the root record with our DMARC builder and progress past p=none once your reports are clean.

The Buttondown gotcha

NS delegation gives Buttondown the whole subdomain, not two records in it. After the managed setup, nothing you add at your DNS host under mail.example.com is visible to the internet; Buttondown's nameservers answer for every name beneath it. That is the point (it is how Buttondown rotates partners without a ticket to you), but it has consequences. You cannot host anything there: Buttondown is explicit that NS and CNAME records cannot coexist at the same name, so a newsletter archive at newsletter.example.com and a sending domain at mail.example.com have to be two different subdomains. You cannot add your own MX, TXT, or DMARC record under it. And when you audit your DNS, the delegated subdomain will show up as an NS record with no visible DKIM or SPF beneath it, which is correct, not broken. If you would rather keep every record in your own zone, use the manual setup; it works, and Buttondown supports it indefinitely, but you lose the partner switching.

Do not add Buttondown to your root SPF record. Buttondown's own SPF FAQ shows merging a Buttondown include into a Google Workspace record, which applies only if Buttondown asked you for an SPF entry on the domain you send from. In the managed setup, the SPF that matters is the one Buttondown publishes for the return path under your delegated subdomain, and no Buttondown message uses example.com as its Return-Path, so an include at the root does nothing except spend one of your ten lookups. Two more things worth knowing: a new sending domain is throttled per hour until Buttondown sees baseline engagement, so a quieter-than-expected first week in your DMARC reports is expected. And if you run several newsletters, each can have its own sending domain at no cost, while reusing one domain across newsletters makes Buttondown set up the records automatically.

Confirm it worked

• Check Settings > Sending domain. After Check records the domain should show as verified. A managed setup that will not validate is almost always a full domain typed into the Host field; a manual one is almost always a proxied CNAME on Cloudflare.
• Send an issue and read the headers. Send to yourself, open the message, and confirm the From is @mail.example.com, the DKIM signature shows d=mail.example.com, the Return-Path sits under your subdomain rather than buttondown.email, and the result is dmarc=pass. Our header analyzer reads it back plainly.
• Watch the reports. Buttondown mail appears in your DMARC aggregate reports under mail.example.com, aligned and passing, from whichever partner Buttondown routed through that week. If the partner changes and the row keeps passing, the delegation is doing its job; trustyourinbox labels the source either way.