Chargebee SPF, DKIM and DMARC setup, step by step

Chargebee Billing can authenticate customer notifications through its own SMTP service or through a separately connected email provider. For Chargebee SMTP, request Domain Authentication from Chargebee Support, publish the records issued for your domains, and complete support verification. For custom SMTP or OAuth connections, authenticate the domain with the provider that actually delivers the email. In either case, finish by checking a fresh notification for a passing, aligned signature from your intended domain. Chargebee Domain Authentication and SMTP configuration.

This guide covers Chargebee Billing 2.0 customer notifications, not every Chargebee product or email generated outside the selected site. No customer account, DNS zone or delivered message was tested for this guide.

Choose the route before changing DNS

The sending service is the system that transmits the notification, which may differ from the application that creates the invoice. Start with the site's actual email configuration.

The current SMTP documentation offers Basic Authentication and OAuth options. Chargebee's OAuth documentation distinguishes Microsoft's SMTP/XOAUTH2 transport from Google's Gmail API transport, even though both connections are managed in the SMTP settings area. Do not assume that everything under that menu uses the same SMTP server. OAuth authentication.

Prepare a small inventory: site and test/live environment, notification categories, selected transport, From addresses, domain owner, DNS provider and the person responsible for billing continuity. A receipt from a test site is not acceptance evidence for a production renewal notice that uses another sender profile.

Configure DKIM for Chargebee SMTP

Prepare sender profiles and DNS ownership

Chargebee requires removing sender profiles using chargebee.com and profiles whose domains you cannot update in DNS before native onboarding. Review the notifications that depend on those profiles and arrange approved replacement senders before removing anything. This is particularly important for scheduled invoices and dunning notices. Domain Authentication prerequisites.

Have the DNS owner export the existing records and identify the authoritative zone. Access to a registrar account does not necessarily mean that registrar hosts the live DNS. You need the records for each sender domain, not just whichever company domain is easiest to edit.

Obtain records and complete activation

1. Ask Chargebee Support to onboard the correct site to Domain Authentication.
2. Receive the domain-specific DNS package. Preserve every supplied owner name, record type and value.
3. Have the DNS owner publish the records after checking for conflicts.
4. Reply to the support email when publication is complete.
5. Retain Chargebee's verification confirmation. Its documentation says signing starts automatically after successful onboarding. Native onboarding and activation.

There is no universal selector or copy-and-paste key in this guide. Use the issued record types, including CNAME or TXT only when specified, and never generate a replacement DKIM key yourself for Chargebee's signing infrastructure. Public-key publication and possession of the matching private signing key must agree. A website screenshot cannot establish that relationship. DKIM signing and DNS key retrieval.

Authenticate a custom SMTP or OAuth connection

Authenticate the intended sender domain with your chosen provider first. Obtain its account-generated DKIM records and, where supported, its custom MAIL FROM or return-path configuration. Publish and verify those values in that provider before switching billing traffic.

For a password-based SMTP provider, open Settings > Configure Chargebee > Email Notifications > Configure SMTP server > Basic Auth. Enter the provider's hostname, credentials, encryption type and matching port. Chargebee's documented sequence uses Validate and Send Test Email, then Save after receipt. That button sends mail; use an approved test recipient and harmless content. A successful connection test still needs the message checks below. Basic SMTP setup.

For Microsoft 365 or Google Workspace business accounts, select the OAuth option and complete the organization's approved authorization flow. Confirm the connected mailbox and its permission to send as the notification address. OAuth authorizes application access; it does not replace SPF, DKIM or DMARC. Chargebee documents only one active SMTP configuration at a time. Plan the transition before disconnecting a working route, because disconnection stops sending through it. OAuth setup and connection management.

For a SendGrid connection, use the SendGrid domain-authentication guide for the external provider's SPF and DKIM workflow, then return here to validate the Chargebee-generated notification.

Keep passwords, API keys and tokens out of DNS, screenshots, shared worksheets and support attachments. DNS verification records are public; SMTP credentials are not.

What SPF record does Chargebee need?

There is no single Chargebee SPF include that applies to every sending route. For native Domain Authentication, use the support-issued DNS package. For an external route, follow that provider's instructions for the account and exact envelope domain. Do not add a guessed include:chargebee.com or copy a different customer's records.

SPF evaluates the SMTP MAIL FROM domain, normally visible as the received message's Return-Path and reported as smtp.mailfrom. It does not authenticate the visible From address directly. A provider-owned return path can pass SPF without aligning with your company domain. Publishing a TXT record at example.com cannot force the service to use example.com as its MAIL FROM. SPF identities.

Before modifying SPF:

• Query the exact owner specified by the provider and compare it with the envelope identity used on messages.
• Maintain one TXT record beginning v=spf1 per owner. Merge required authorization into an existing policy; do not add a second SPF policy or remove unrelated TXT verification records.
• Preserve legitimate senders and the reviewed terminal qualifier. An authorization inserted after an all mechanism will not be reached.
• Check the full evaluation, including nested include and redirect dependencies, against the ten DNS-lookup-causing-term limit. Do not fix excess lookups by deleting active senders or copying today's provider IPs into a static list. SPF record rules and limits.

A separate custom return-path domain needs its own provider-supported setup. Do not overwrite the MX records that receive employee email to create one.

If the existing SPF policy uses redirect=, reconcile its authorizations with the DNS owner before changing it. An all mechanism makes redirect ineffective regardless of their order; do not append all as an automatic merge step. SPF qualifiers express authentication results, not a guaranteed receiver delivery or rejection decision. SPF all and redirect processing.

Publish DNS at the correct owner name

These examples explain name placement only. selector-from-provider is a placeholder, not a Chargebee selector. Keep the record's actual type and target exactly as issued.

If billing.example.com is delegated to separate nameservers, edit that child zone, not an ineffective copy in the parent. Confirm the completed fully qualified name before saving. A panel that appends example.com twice creates a different, unusable owner.

If _domainkey.billing.example.com itself is delegated, the example issued key owner becomes selector-from-provider in that delegated zone. Preserve the existing NS records and publish with that authority, not in an inactive parent copy. Do not change nameservers, DNSSEC or forwarding merely to publish authentication records. DNS zone boundaries.

For a CNAME, do not place other ordinary records at the same owner or overwrite an existing active selector. Ask the provider for a compatible selector if necessary. Keep mail-authentication CNAMEs DNS-only rather than HTTP-proxied. Do not add a URL scheme or path to a DNS target. Only TXT public-key values belong in a TXT field; private DKIM keys never belong in DNS.

Apply the following only when the account's issued package contains CNAME aliases, not to a direct-TXT key. Where literal CNAME answers are required, the end state is a DNS-only alias returning the exact issued target, without HTTP proxying or flattening hiding it. Turn the relevant per-record Flatten control off when available and ensure applicable zone-wide settings preserve those aliases. On Cloudflare, flatten-all cannot be overridden per record; apex CNAMEs are flattened by default, and same-zone targets are flattened regardless of that setting. These are conditional DNS-host behaviors, not assumed controls in every panel. If mandatory behavior or a shared setting prevents the required answer, stop and coordinate a supported configuration with the DNS owner and sending service. Do not blindly change the whole zone or remove an existing NS delegation. Cloudflare CNAME verification, flattening controls and limits.

Preserve DMARC and monitor the right domain

DMARC passes when either SPF passes and aligns with the visible From domain or DKIM passes and aligns. With relaxed alignment, the organizational domains match; strict alignment requires an exact domain match. Thus, a signature for example.com may align with billing.example.com under relaxed adkim=r but not under strict adkim=s. Check the policy actually applicable to the sender domain rather than assuming the default. DMARC alignment.

Chargebee explicitly says an existing DMARC record does not need to be added again during onboarding. Retain established enforcement and reporting settings. If no applicable policy exists and the domain owner chooses a monitored introduction, this is an illustrative starting policy, not a replacement for an existing one:

Owner: _dmarc.example.com
Type: TXT
Value: v=DMARC1; p=none; rua=mailto:dmarc-reports@example.com

Replace the domain and reporting mailbox before use. In an example.com zone whose editor appends the zone name, enter _dmarc to create _dmarc.example.com. For a deliberate child-domain policy, the owner is _dmarc.billing.example.com, entered as _dmarc.billing in the parent zone or _dmarc in the delegated child zone. Check inherited policy before adding a child override. Do not create duplicate DMARC policies at one owner.

Provision and monitor the reporting destination. Aggregate reports help identify recurring authentication and alignment failures, not whether an individual invoice was read or placed in the inbox. Review every legitimate sender before increasing enforcement. DMARC aggregate reporting.

Compare the Organizational Domain of the aggregate-report URI's host with the Organizational Domain of the domain where the DMARC policy was found, which is not necessarily the visible From domain. If they differ, the report-generating receiver must check DNS authorization. A destination within the same Organizational Domain as the policy domain is excepted; a different hostname alone does not make it external. Follow the reporting service's exact authorization instructions when needed. This protocol check is separate from the domain owner's approval to share report data with that recipient. RFC 9990 section 4.

Verify DNS, then verify a real notification

DNS and provider acceptance

Replace every placeholder below. These are read-only queries; they do not configure the domain.

dig +short NS example.com
dig +short NS billing.example.com
dig @ns1.dns-provider.example selector-from-provider._domainkey.billing.example.com CNAME +noall +answer
dig +short TXT selector-from-provider._domainkey.billing.example.com
dig +short TXT envelope-domain.example
dig +short TXT _dmarc.billing.example.com
dig +short TXT _dmarc.example.com

Use an actual authoritative nameserver in the @ query. Compare authoritative answers with a public recursive resolver after the previous TTL expires. Check every issued record, not only the first selector. A CNAME must return the supplied target and lead to the expected public key; a direct DKIM TXT record must expose the complete public key. Query the record type actually issued. An empty answer can mean the wrong type or owner, not necessarily that propagation is pending.

Accept the configuration stage only when the issued records match publicly and Chargebee has confirmed native onboarding, or the external provider has verified its domain and the connection is active.

Delivered-message acceptance

Send an authorized, harmless notification through the intended site, sender profile and transport to a mailbox whose raw source you can inspect. Use the recipient system's trusted Authentication-Results, not a header supplied by the sender. Authentication-Results trust boundary.

Establish which results were generated inside the receiving service's known processing boundary and how that service removes, ignores or distinguishes externally supplied Authentication-Results. Use its documented handling or ask the receiving-mail administrator to confirm the boundary. A familiar authserv-id string or header position alone is not proof. Reject attacker-supplied or otherwise untrusted fields; obtain the receiver's own diagnostic evidence when provenance is uncertain. Operational receiving-result trust.

Record the visible From domain, smtp.mailfrom, SPF result, DKIM d= domain, DKIM s= selector and DMARC result. Accept the setup only when the intended domain's signature both passes and aligns, the approved visible From is unchanged, and the trusted receiver reports dmarc=pass for that intended From domain. A passing provider-domain signature or an overall DMARC pass through SPF alone does not prove that branded DKIM is working.

For direct delivery, investigate any SPF fail, softfail, neutral, none, temperror or permerror. An SPF pass that is unaligned can coexist with a valid DMARC pass through aligned DKIM; document that limitation separately from an actual SPF error. Retest after repairs. Forwarded copies can behave differently, so retain a direct-delivery sample as well.

Repeat for materially different From domains and routes. Save only a minimized header extract, with customer addresses, invoice information and message identifiers removed where they are unnecessary.

Troubleshooting Chargebee authentication

See the provider's basic SMTP troubleshooting, OAuth troubleshooting and sender-rewriting explanation.