Atlassian SPF and DKIM setup

What you are setting up

Out of the box, Jira Cloud, Jira Service Management, and Confluence Cloud send every notification from an atlassian.net address. Atlassian lets an organization admin replace that with an address on your own domain, and the point of the DNS work is that the message is then signed for your domain rather than Atlassian's. The work has four parts, in order: add the email domain in Atlassian Administration, publish the DNS records it gives you, add the specific addresses that may send, and then have a Jira site admin or Confluence admin choose one of those addresses in the product. Atlassian is blunt about why the DNS step matters: notifications sent from a domain other than atlassian.net “can be rejected by DMARC if sent without a domain-specific DKIM signature.” The records are that signature.

One thing to know before you start: this email domain is a separate object from the domain you may already have verified under user management to claim accounts. Verifying a domain for account management does nothing for notification email, and Atlassian says so on the add-domain page. You add it again, under Emails.

Publish SPF and DKIM

Go to admin.atlassian.com, pick your organization if you have more than one, and open Organization settings > Emails. On the Email domains tab, click Add domain and enter your company's domain. Atlassian then shows the DNS records modal (you can reopen it later with See DNS records), listing five records (Atlassian says five or six): an SPF TXT, two DKIM CNAMEs labeled DKIM1 and DKIM2, a BOUNCECNAME, and a verification TXT. Copy each name and value from the modal, because the DKIM selector, the CNAME targets, and the verification token are generated for your organization. The shape is:

Type:  TXT     (SPF)
Host:  @
Value: v=spf1 include:_spf.atlassian.net ~all

Type:  CNAME   (DKIM1)
Host:  atlassian-xxxxxx._domainkey
Value: (the target shown in the DNS records modal)

Type:  CNAME   (DKIM2)
Host:  atlassian-xxxxxx._domainkey
Value: (the target shown in the DNS records modal)

Type:  CNAME   (Bounce, shown as BOUNCECNAME)
Host:  (the host shown in the DNS records modal)
Value: (the target shown in the DNS records modal)

Type:  TXT     (Verification)
Host:  (the host shown in the DNS records modal)
Value: atlassian-sending-domain-verification=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The DKIM hosts are atlassian- followed by a short hex string, one per key, and both are CNAMEs so Atlassian can rotate a key without you touching DNS; the second record exists for exactly that reason. If your domain already has an SPF record, merge include:_spf.atlassian.net into it rather than publishing a second one; Atlassian's own troubleshooting page says to merge multiple SPF records into one because they produce a PermError. Atlassian re-checks the records every 24 hours on its own, and you can trigger a check yourself from the Email domains tab; matched records show one status icon, unmatched ones another you can hover for detail. Once everything matches the domain flips from unverified to Active, and Atlassian says provisioning can take up to 72 hours.

With the domain Active, stay under Emails and add the addresses that are allowed to send, such as jira@yourdomain.com or confluence@yourdomain.com. Then hand off to the product admins. In Jira, a site admin opens Settings > Spaces, picks the space, chooses More actions > Space settings > Notifications > Internal notifications, clicks Edit under Notification email, then Edit on the email card, and picks the custom address from the Email dropdown; it becomes the sender (and reply address) for that space only. In Confluence, the setting is site-wide: a Confluence admin opens the wheel icon, then Settings > Configuration > Notifications, chooses the address in the Email addresses field, and Save changes. Atlassian says the Confluence change can take up to an hour to apply.

Add DMARC

Standard _dmarc TXT record, nothing Atlassian-specific. Start in monitor-only mode and ramp up:

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

Build it with our DMARC builder and progress past p=none once your reports are clean. Atlassian publishes no DMARC record for you and asks for none; the five records above are what make your Atlassian mail pass the DMARC policy you publish.

The Atlassian gotcha

Picking the address before the DNS is Active. The custom address shows up in Jira's and Confluence's dropdowns as soon as the organization admin adds it, so a space admin can select it while the domain is still unverified. At that point notifications go out From your domain with Atlassian's own signature, which is exactly the “rejected by DMARC” case Atlassian warns about, and it bites hardest on a domain already at p=quarantine or p=reject: your own ticket updates land in spam or vanish. Finish the DNS, wait for Active, then switch the sender.

Partial domains and half-matched values. The address must be entirely on your domain; Atlassian documents that a partially custom domain such as jira@customPrefix.jira-dev.com will not work. And the checker compares each value exactly, so a DNS host that appends your domain to the CNAME host (giving atlassian-xxxxxx._domainkey.yourdomain.com.yourdomain.com) or a stray space in the verification token keeps the domain unverified with no more specific error. Look up each record from outside your network and compare it character by character with the modal. Two smaller ones: the bounce CNAME is the return path for the notifications, so leave it in even though it looks optional, and Confluence's “shared with you” emails keep showing Atlassian as the sender even after you switch the domain, which is documented, not a misconfiguration.

Confirm it worked

• Check the Email domains tab. Every record should show the matched icon and the domain should read Active. If one record stays flagged after propagation, re-run the check and hover the status for which value did not match.
• Trigger a notification and read the headers. Comment on a work item or a page, open the notification at the other end, and confirm the DKIM signature shows d=yourdomain.com with an s=atlassian- selector, the Return-Path is on a host under your domain, and the result is dmarc=pass. Our header analyzer reads it back plainly. If the signing domain is still atlassian.net, the space is not using the custom address yet.
• Watch the reports. Atlassian should appear as an aligned, passing source on both SPF and DKIM in your DMARC aggregate reports, listed as an identified sender in trustyourinbox. A burst of Atlassian mail failing DKIM alignment usually means a space switched to the custom address before the domain went Active.