How to set up DMARC/DKIM/SPF for Buttondown
Updated on 25 Oct 2026: We clarified Buttondown bounce-domain setup, delegated DMARC records, and live-message authentication checks.
Buttondown custom-domain authentication works best when the sending domain comes first, followed by verification of SPF, DKIM, and DMARC with a real Buttondown message. For new Buttondown sending subdomains, the cleanest path is managed DNS delegation: Buttondown shows two NS records and manages the sender-specific SPF, DKIM, return-path, and tracking records below that subdomain.
For root-domain sending, or Buttondown's manual setup, copy the displayed records instead of guessing values. DMARC applies to the visible From domain and gives mailbox providers a policy for messages that fail aligned authentication.
Add your domain
Add the Buttondown sending domain before changing SPF, DKIM, or DMARC because the DNS records depend on the exact From domain used in Buttondown. A dedicated subdomain such as newsletter.example.com separates Buttondown's DNS configuration from normal corporate mail. Before editing DNS, save the current records and inventory every service sending with the same From domain so existing authentication stays intact.
- 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 authoritative DNS host. Use the sending-subdomain label, such as newsletter, when the panel appends your domain. These are subdomain records, not replacements for your root domain's nameservers.
- 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.
An existing verified manual setup can stay in place; switching to managed DNS is optional. Buttondown's managed DNS announcement explains how delegation lets Buttondown maintain sending records without repeated changes at your DNS host.
Buttondown sending domain settings with managed DNS delegation records
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.
- Tracking: Buttondown configures the custom tracking domain automatically.
- 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 every SPF, DKIM, return-path, and tracking record Buttondown displays.
- Tracking: Enable click tracking under Settings, Sending domain, then Add-ons and publish the displayed CNAME.
- Replies: Provide your own MX record for inbound replies. New manual setups default to reply tracking off; existing setups retain their reply behavior. Manage reply tracking under Add-ons. A custom Reply-To sends replies directly to that inbox and bypasses tracking.
- Risk: Future sending-path changes require another manual DNS update.
Set up SPF
SPF (Sender Policy Framework) authorizes sending servers for the envelope sender domain, usually shown in Return-Path. Buttondown supports return-path alignment, so SPF should pass after the sending domain is verified. Check DMARC alignment separately against the policy's SPF alignment mode. In managed setup, Buttondown handles the underlying SPF and return-path DNS below the delegated subdomain. In manual setup, publish exactly what Buttondown displays.
- Check the mode: If Buttondown shows managed NS records, publish those and let Buttondown manage SPF below the subdomain.
- Merge only when requested: If Buttondown supplies an SPF include, merge it into the existing SPF record at the hostname it specifies, before the final all mechanism. Preserve other authorized senders. A custom return path does not automatically require a root-domain include.
- Keep one SPF record: Publish at most one TXT record beginning v=spf1 at each hostname. Multiple SPF records cause PermError; unrelated TXT records can coexist.
- Watch lookup count: SPF evaluation permits at most ten DNS-querying mechanisms and modifiers, including those reached through nested includes. If the SPF record being evaluated is crowded, remove obsolete authorizations or use a separate return-path subdomain configured by Buttondown.
SPF merge template, replace placeholders before publishingdns
Name: <hostname specified by Buttondown> Type: TXT Value: v=spf1 <existing mechanisms> include:<include domain supplied by Buttondown> <existing all mechanism>
Use that template only if Buttondown supplies an include; it is not a ready-to-publish record. After DNS publishes, check the exact envelope sender domain from a new message, not just the visible From domain. SPF records are not inherited by subdomains. RFC 7208 defines the SPF identity and lookup limit. A syntax check still needs a live Buttondown test to confirm SPF passes with DMARC alignment.
SPF checker
Find SPF syntax issues, lookup limits, and weak records.
?/16tests passed
If SPF fails for the active Return-Path domain, fix that before moving to DMARC enforcement. If SPF passes but a delivered test still shows SPF alignment errors, compare the Return-Path and visible From domains. Check that Buttondown verified the intended sending domain and that the test used its current sending configuration.
Buttondown DNS verification checklist for SPF and the Return-Path
Set up the bounce domain
The bounce domain, also called the custom Return-Path or MAIL FROM domain, receives delivery failures and is the domain SPF evaluates for normal newsletter messages. A bounce subdomain supports relaxed SPF alignment when it shares the organizational domain with the visible From domain; strict SPF alignment requires an exact domain match. It is separate from the Reply-To address used for subscriber replies.
- Find the record: In manual setup, locate the bounce or return-path record in Buttondown's sending-domain DNS checklist. Copy its exact type, hostname, and target; there is no universal value to substitute.
- Publish it exactly: If the record is a CNAME, keep it DNS-only and do not add a TXT or MX record at that same hostname.
- Verify the domain: Wait for Buttondown to verify the record. With managed DNS, Buttondown maintains these records inside the delegated subdomain.
- Check a new message: Inspect Return-Path and the receiving server's Authentication-Results. Confirm spf=pass and compare smtp.mailfrom with the visible From domain using your DMARC alignment mode.
Use the account-specific records in Buttondown's sending-domain instructions. Keep your normal inbound-mail MX records in place; the bounce hostname has a different purpose.
Set up DKIM
DKIM (DomainKeys Identified Mail) verifies a message signature using a public key in DNS. DMARC passes when DKIM passes with alignment to the visible From domain. Managed setup lets 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 dkim=pass in the receiving server's Authentication-Results. Compare the signature's d= domain with the visible From domain; the presence of a DKIM-Signature header alone does not prove verification.
Alternative DKIM templates, use only the type Buttondown suppliesdns
# CNAME option Name: <selector>._domainkey.newsletter.example.com Type: CNAME Value: <exact target supplied by Buttondown> # TXT option Name: <selector>._domainkey.newsletter.example.com Type: TXT Value: <complete DKIM public-key record supplied by Buttondown>
These are alternative templates, not two records to publish at the same name. Use Buttondown's actual selector, record type, and value. Publish every selector it supplies, and keep existing selectors used by other sending services.
Buttondown DKIM verification screen with selector names and DNS records
Why DKIM matters when SPF fails
DMARC only needs one aligned pass: SPF or DKIM. Configure both mechanisms, but expect ordinary forwarding to break SPF when the forwarding server is not authorized by the original envelope sender. An unchanged DKIM signature can survive forwarding and still provide a DMARC pass.
Set up DMARC
DMARC (Domain-based Message Authentication, Reporting, and Conformance) policy discovery starts with the visible From domain. If the From address is hello@newsletter.example.com, the full record name is _dmarc.newsletter.example.com. Keep a DMARC record at the organizational domain, _dmarc.example.com, too. If the From address is hello@example.com, publish at _dmarc.example.com.
- Identify DNS control: For a managed subdomain, look up its DMARC record and confirm the policy and reporting destination. Buttondown controls DNS below the delegated name; arrange changes there with Buttondown. A record added below that delegation in your parent DNS zone is not authoritative. For manual setup, publish at your DNS host.
- Start at monitoring: Use p=none unless the domain already has a tested quarantine or reject policy.
- Send reports somewhere useful: Replace the sample rua mailbox with an address that receives and processes aggregate XML reports. To monitor the domain in Suped's DMARC reporting product, use the reporting address supplied for that domain. If it is an external destination, confirm the report recipient's DNS authorization.
- Use one record: Only one DMARC TXT record is valid at a single _dmarc hostname.
- Skip historic sampling: Do not add pct. RFC 9989 marks that tag historic, so stage policy by reviewing reports before changing p.
- Generate safely: Use the DMARC generator if you need a record with current reporting and policy settings.
Starter DMARC record for newsletter.example.com, replace the reporting addressdns
Name: _dmarc.newsletter.example.com Type: TXT Value: v=DMARC1; p=none; rua=mailto:dmarc@example.com
|
|
|
|---|---|---|
hello@example.com | _dmarc.example.com | _dmarc |
hello@newsletter.example.com | _dmarc.newsletter.example.com | _dmarc.newsletter |
Full DNS names; the Host field depends on which DNS zone you are editing.
After publishing, check the hostname that matches Buttondown's visible From domain and the organizational-domain record when the two differ. If the From domain has no record, receivers discover an applicable parent policy. An explicit subdomain record supplies its own policy and reporting destination; the parent sp tag controls subdomain policy only when the parent record is selected. External report destinations require authorization under RFC 9990.
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. In an example.com zone, many panels expect _dmarc for the root domain and _dmarc.newsletter for the newsletter subdomain. Inside a delegated newsletter.example.com zone, the label is _dmarc. 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. 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: Open the message's raw source or original headers. In the receiving server's Authentication-Results, confirm spf=pass, dkim=pass, and dmarc=pass. Compare smtp.mailfrom, header.d, and header.from to identify the domains actually evaluated.
- Check domain matching: The DKIM d= domain or SPF return-path domain must share the organizational domain with the visible From domain under relaxed alignment, or match it exactly when strict alignment is configured.
- Wait for DNS: If you just changed records, allow cached answers to expire according to their TTL, then retry verification in Buttondown. Use a fresh test after verification succeeds.
- Avoid stale sends: Do not judge the setup from an old message sent before Buttondown verified the domain.
Fast failure map
- SPF fail: Check the active return-path record, duplicate SPF TXT records, missing supplied values, nested-lookup limits, 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 aligns with the visible From domain.
- No report: Check the rua address, external-destination authorization, and whether a subdomain record overrides the expected parent reporting address. Reports usually cover a daily window and arrive after processing; not every receiver sends them.
A full-path check is to send a Buttondown message to Suped's email tester address. Its results cover authentication and headers as well as common content issues. A passing test does not guarantee inbox placement.
Email tester
Send a real email to this address. Suped shows a results button when the test is ready.
?/43tests passed
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.
Warm up a migrated list
Authentication does not create sender reputation by itself. Plan a warm-up when migrating 10,000 subscribers or more. Buttondown requires a custom sending domain for imports above 10,000 subscribers and automatically throttles and audits initial sends while it measures engagement and delivery problems.
- Clean the list first: Remove invalid addresses, prior unsubscribes, and recipients without a current reason to expect the newsletter.
- Start with engaged readers: Send the first messages to subscribers who recently opened, clicked, or replied.
- Expand gradually: Increase the audience only while delivery metrics meet Buttondown's standards: permanent failures at 1% or lower, temporary failures at 5% or lower, and complaints at 0.1% or lower.
- Invite replies: Acknowledge the migration and ask engaged readers to reply to the first messages.
- Pause on deterioration: Fix list or authentication problems before widening the next send.
Let Buttondown control the pace
Buttondown caps hourly sending for new senders until engagement and reputation reach its baseline. Treat that throttling as part of the migration plan and watch the first sends before expanding the audience.
Monitor Buttondown authentication
A Buttondown setup can pass today and break after a DNS edit, domain change, selector rotation, or sender migration. Suped's product turns aggregate DMARC reports into source-level authentication results and alerts, which helps track Buttondown alongside the domain's other authorized senders.
- Review sending sources: Use Suped's source-level results to review Buttondown alongside other authorized senders and investigate unexpected traffic.
- Act on alerts: Report-driven alerts flag SPF, DKIM, or DMARC pass-rate drops when new data arrives.
- Investigate failures: Review the affected source and its authentication results, then compare them with Buttondown's current DNS checklist.
- Watch reputation: Use Suped's blocklist (blacklist) monitoring to check domain and sending-IP listings alongside authentication failures.
For ongoing DMARC monitoring, use the reporting address supplied by Suped's product and verify that reports reach it. Alerts depend on incoming report data, so test fresh messages after DNS changes instead of waiting for the next aggregate report.
Choose a DMARC enforcement policy
Do not move a Buttondown domain straight to p=reject unless every legitimate sender authenticates. A dedicated Buttondown-only subdomain can use reject after sustained clean reports. For a root domain used by people or mailing lists, RFC 9989 warns that reject can disrupt indirect mail, so assess those flows before moving beyond quarantine.
- Collect reports: Run p=none until Buttondown and every other legitimate source is visible across a normal sending cycle.
- Fix legitimate sources: Configure aligned DKIM and SPF for Buttondown and every other authorized source. A message needs only one aligned pass for DMARC; deployment should support both mechanisms. Do not rely on SPF alone when publishing p=reject.
- Use quarantine first: Move to p=quarantine after known legitimate sources pass and review the resulting dispositions.
- Reserve reject for the right domain: Use p=reject on a dedicated sending domain after failures are unauthorized. Keep indirect mail risks in view for general-purpose domains.
- Keep watching: After enforcement, a sender break can affect delivery, so continue reviewing reports and alerts.
Policy readiness checks
Use evidence from a normal sending cycle before tightening DMARC on a Buttondown domain.
Hold at p=none
Unknown sources
Legitimate sources still fail or have not appeared in reports.
Test quarantine
Sources verified
Known legitimate sources pass aligned authentication consistently.
Consider reject
Dedicated domain
The domain is dedicated to controlled sending and remaining failures are unauthorized.
Use source-level reports in Suped's product when deciding whether to tighten policy. Hosted DMARC supports later policy changes after its initial DNS setup. For a Buttondown-managed subdomain, first confirm with Buttondown how its authoritative DMARC record can be configured; Hosted DMARC requires control of the relevant DNS record.
Enforcement checklist
- Buttondown passes: Live test emails pass aligned 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 enforcement affects mail handling.
- Policy fits the domain: Reject is limited to a controlled sending domain, or indirect mail has been assessed first.
FAQ
Yes, for clean authentication on your own domain. Buttondown can send from its shared domain by default, while custom-domain sending should have aligned SPF and DKIM plus a DMARC policy and reporting record.
Use managed DNS for a dedicated sending subdomain when Buttondown offers it. Use manual DNS for root-domain sending or when the required NS delegation is unavailable. Manual setup also leaves MX, tracking, and reply behavior under your control.
Publish an explicit DMARC record for the visible From domain and keep one at the organizational domain when they differ. For hello@newsletter.example.com, the full name is _dmarc.newsletter.example.com. With managed DNS, check that record publicly and arrange changes with Buttondown; a copy in the parent DNS zone below the delegation has no effect. An explicit subdomain record has its own policy and reporting destination.
DMARC passes when either SPF or DKIM passes with alignment to the visible From domain. Forwarding often breaks SPF because the forwarding server is not authorized by the original envelope sender. An unchanged, aligned DKIM signature can still produce a DMARC pass. Keep both mechanisms configured for normal Buttondown sends.
Use p=reject on a dedicated Buttondown sending domain after reports show every legitimate source passing aligned authentication. For a root domain used by people or mailing lists, assess indirect mail first because reject can disrupt forwarding. Suped's product can show source-level results and support policy changes.
Plan a warm-up when migrating 10,000 subscribers or more. Start with recently engaged readers, keep the list clean, and let Buttondown's initial throttling control the pace before expanding the audience.
