Buttondown custom-domain authentication works best when I start with the sending domain, then verify SPF, DKIM, and DMARC from a real Buttondown message. For new Buttondown sending subdomains, the cleanest path is managed DNS delegation: Buttondown shows two NS records, and Buttondown manages the sender-specific SPF, DKIM, and return-path records under that subdomain.
If you send from a root domain, or you choose Buttondown's manual setup, copy the records Buttondown displays instead of guessing values. DMARC then sits on the visible From domain and tells mailbox providers what to do when a message fails authentication.
Add your domain
I add the Buttondown sending domain before changing SPF, DKIM, or DMARC because the DNS records depend on the exact From domain you use in Buttondown. A dedicated subdomain such as newsletter.example.com keeps Buttondown isolated from your normal corporate mail.
- Open Buttondown settings: Go to Settings, then Domains, then the sending domain area.
- Choose the sending domain: Use a dedicated subdomain for new newsletters, usually mail.example.com or newsletter.example.com.
- Use managed setup: For a subdomain, publish the two NS records Buttondown shows at your DNS host.
- Use manual setup: For a root domain, or when you cannot delegate a subdomain, copy Buttondown's manual DNS records exactly.
- Verify in Buttondown: Return to the Domains page and wait for Buttondown to mark the sending domain as verified.
Buttondown Settings Domains screen showing a sending domain setup
Keep hosting and sending DNS separate
If you already use a Buttondown hosting domain with a CNAME record, do not delegate that same exact name with NS records. DNS does not allow CNAME and NS records at the same host name.
- Good split: Use www.example.com for archives and newsletter.example.com for sending.
- Bad split: Do not put Buttondown archive hosting and Buttondown sending delegation on the same hostname.
Managed setup
- Best fit: New Buttondown sending subdomains.
- DNS change: Two NS records at the delegated subdomain.
- Benefit: Buttondown can update sending records without another DNS change.
Manual setup
- Best fit: Root-domain sending or DNS hosts that block NS delegation.
- DNS change: Copy each Buttondown SPF, DKIM, return-path, and tracking record.
- Risk: Future sending-provider changes require another manual DNS update.
Set up SPF
Buttondown supports return-path alignment, so I expect SPF to pass and match the visible From domain once the sending domain is verified. In managed setup, Buttondown handles the underlying SPF and return-path DNS below the delegated subdomain. In manual setup, you need to publish exactly what Buttondown gives you.
- Check the mode: If Buttondown shows managed NS records, publish those and let Buttondown manage SPF below the subdomain.
- Merge root SPF: If you send from example.com and Buttondown shows a manual SPF include, merge it into the existing SPF record instead of creating a second SPF TXT record.
- Keep one SPF record: Every hostname gets only one SPF TXT record. Multiple SPF records make SPF fail.
- Watch lookup count: SPF has a 10 DNS-lookup limit. If your root SPF is already crowded, use Hosted SPF or split Buttondown onto a subdomain.
Manual SPF merge patterndns
Name: example.com Type: TXT Value: v=spf1 include:buttondown-provided-value.example ~all
After DNS publishes, check the exact From domain or delegated sending subdomain. I do not treat a green SPF syntax result as enough; I also send a real Buttondown test message later to confirm the return-path domain matches the From domain for DMARC.
SPF checker
Find SPF syntax issues, lookup limits, and weak records.
?/16tests passed
If SPF fails in the checker, fix that before moving to DMARC enforcement. If SPF passes but a delivered test still shows SPF alignment errors, inspect the Return-Path header. With Buttondown, that usually means the sending domain is not fully verified, the old path is still being used, or the From address is not the domain you authenticated.
Buttondown sending domain DNS checklist with SPF verified
Set up DKIM
DKIM is the authentication method I care about most for Buttondown because DMARC can pass when DKIM passes and the DKIM signing domain matches the visible From domain. Managed setup should let Buttondown create and maintain the DKIM selectors below the delegated sending subdomain.
- Use managed selectors: If Buttondown manages the sending subdomain, wait for the DKIM rows to show verified in Buttondown.
- Copy manual selectors: If Buttondown shows manual DKIM records, copy every selector name and value exactly.
- Do not rename selectors: DKIM selector names are part of the signature lookup. Changing them breaks verification.
- Avoid proxying: If your DNS host has proxy controls, leave DKIM CNAME records as DNS-only.
- Test a send: Send a Buttondown email and confirm the message has a DKIM-Signature header with your sending domain.
Manual DKIM record patternsdns
Name: selector._domainkey.newsletter.example.com Type: CNAME Value: target-provided-by-buttondown.example Name: selector._domainkey.newsletter.example.com Type: TXT Value: v=DKIM1; k=rsa; p=public-key-from-buttondown
Buttondown sending domain screen showing DKIM records
When SPF matching is not enough
DMARC only needs one matching pass: SPF or DKIM. Buttondown supports return-path matching, so I still set up SPF. If you later add another sender that cannot use your return path, SPF alignment errors are acceptable when DKIM passes with the visible From domain.
Set up DMARC
DMARC belongs on the visible From domain, not inside Buttondown. If your Buttondown From address is hello@newsletter.example.com, publish DMARC at _dmarc.newsletter. If your From address is hello@example.com, publish it at _dmarc on the root domain.
- Start at monitoring: Use p=none unless your domain is already at quarantine or reject. If it is, keep that stronger policy.
- Send reports somewhere useful: Replace the sample rua mailbox with the reporting address you monitor.
- Use one record: Only one DMARC TXT record is valid at a single _dmarc hostname.
- Generate safely: Use the DMARC generator if you need a record with reporting and staged policy settings.
Starter DMARC recorddns
Name: _dmarc Type: TXT Value: v=DMARC1; p=none; rua=mailto:dmarc@example.com
|
|
|
|---|---|---|
Root | _dmarc | same as root |
Subdomain | _dmarc.sub | own or inherited |
Parked | _dmarc | reject |
Use the row that matches your Buttondown From address.
After publishing the record, check the same hostname that receives Buttondown's visible From mail. This catches the most common mistake: adding DMARC to the organizational domain while sending from a subdomain that has no DMARC record and no useful reporting.
DMARC checker
Look up a domain's DMARC record and catch policy issues.
?/7tests passed
If the checker finds no DMARC record, confirm the DNS host field. Many DNS panels expect only _dmarc for the root domain and only _dmarc.newsletter for a subdomain. Entering the full domain in a panel that appends the zone creates the record at the wrong place.
Verify and troubleshoot
DNS verification inside Buttondown proves the records exist. A delivered message proves the whole path works. I always test with a real Buttondown email because it exposes the active return path, DKIM selector, From domain, and DMARC result in one place.
- Send a real email: Send from Buttondown using the exact From address your subscribers see.
- Inspect authentication: Confirm SPF passes, DKIM passes, and DMARC passes in the receiving result.
- Check domain matching: The DKIM d= domain or SPF return-path domain must match the visible From domain at the organizational-domain level.
- Wait for DNS: If you just changed records, wait for TTL and retry from Buttondown.
- Avoid stale sends: Do not judge the setup from an old message sent before Buttondown verified the domain.
Fast failure map
- SPF fail: Check for duplicate SPF TXT records, missing Buttondown manual include values, or incomplete managed delegation.
- DKIM fail: Check selector spelling, CNAME target values, DNS-only status, and Buttondown verification state.
- DMARC fail: Check whether the passing SPF or DKIM domain matches the visible From domain.
- No report: Check the rua address and confirm mailbox providers have had time to send aggregate reports.
The quickest full-path check is to send a Buttondown message to an email tester address. That gives you one report for SPF, DKIM, DMARC, headers, and common content issues.
Email tester
Send a real email to this address. Suped opens the report when the test is ready.
?/43tests passed
Preparing test address...
I use the tester before changing policy because it catches problems that a DNS-only check misses. A common example is DKIM DNS passing in isolation while the live Buttondown message still signs with an older selector or an unexpected domain.
|
|
|
|---|---|---|
SPF fail | DNS mismatch | Recheck Buttondown records |
DKIM fail | Selector issue | Copy exact selector |
DMARC fail | Domain mismatch | Fix From or DNS |
No reports | Bad rua | Correct mailbox |
Troubleshooting checks after a live Buttondown test send.
Get alerted when it breaks
A Buttondown setup can pass today and break later after a DNS edit, domain change, selector rotation, or sender migration. Suped's product is the best overall DMARC platform for this workflow because it turns raw DMARC reports into Buttondown-specific issues, source changes, and real-time alerts.
- Detect source drift: Suped groups Buttondown separately from your other senders so failures do not hide in aggregate XML.
- Act on alerts: Real-time alerts tell you when SPF, DKIM, or DMARC pass rates drop.
- Fix faster: Issue detection points to the record, source, and likely fix instead of handing you raw XML.
- Watch reputation: Blocklist monitoring tracks domain and IP issues across blocklist and blacklist data.
- Scale cleanly: The MSP dashboard works well when you manage multiple Buttondown newsletters or client domains.
For ongoing DMARC monitoring, Suped's product is practical because it covers DMARC, SPF, DKIM, blocklist checks, and deliverability signals in one place. The free plan is enough for many small newsletters to start watching failures before policy enforcement.
Without alerting
- Slow detection: A broken selector waits until someone inspects headers or reports.
- Raw data: DMARC XML requires manual grouping by source and domain.
- Policy risk: Moving to enforcement is guesswork if legitimate sources are unclear.
With Suped
- Fast detection: Alerts surface Buttondown failures as soon as report data changes.
- Source clarity: Buttondown, corporate mail, and other senders appear as separate sources.
- Action steps: The issue view gives direct fix steps for DNS and authentication errors.
Secure your domain with p=reject
I do not move a Buttondown domain straight to p=reject on day one unless the domain is already fully authenticated across every legitimate sender. The safe path is monitoring first, then quarantine, then reject after report data proves legitimate mail passes.
- Collect reports: Run p=none until Buttondown and every other source is visible in reports.
- Fix all legitimate sources: Buttondown should pass DKIM and SPF, while each other sender needs at least one matching authentication pass.
- Use quarantine first: Move to p=quarantine when only unauthorized mail fails.
- Finish with reject: Move to p=reject once failures are unwanted mail, stale tests, or spoofing attempts.
- Keep watching: After enforcement, alerts matter more because a sender break can cause real rejection.
Policy readiness thresholds
Use these as practical guardrails before tightening DMARC on a Buttondown sending domain.
Hold at p=none
Below 95%
Legitimate sources still fail DMARC or are not clearly identified.
Test quarantine
95-99%
Main sources pass and only low-volume legitimate mail needs review.
Move to reject
99%+
Legitimate sources pass consistently and failures are unwanted mail.
Suped's product is the strongest practical way to reach p=reject because it keeps the policy workflow tied to real authentication data. Hosted DMARC helps stage policy changes without repeated DNS edits, Hosted SPF helps keep SPF within lookup limits, and Hosted MTA-STS can enforce TLS for mail delivery with two CNAME records.
If you want policy staging without editing TXT records every time, Hosted DMARC keeps the DNS side simple while you move through monitoring, quarantine, and reject.
Enforcement checklist
- Buttondown passes: Live test emails pass DKIM, SPF, and DMARC.
- Reports are clean: Aggregate DMARC reports show no legitimate sender failing at scale.
- Alerts are active: Failure alerts are configured before reject blocks mail.
- Policy is staged: Move through none, quarantine, then reject.
