Setting up a custom sending domain

Overview

Adding four DNS records lets Joyous send campaign emails from your own domain (for example engage@yourcompany.com), fully authenticated with DKIM, SPF and DMARC.

Joyous sends email through Mandrill (Mailchimp Transactional), so the records point to Mandrill. You don't need to change your existing SPF record, and your main domain's other mail is not affected.

• Who does it: whoever manages DNS for your domain (usually IT)
• Time: about 15 minutes to add the records; DNS changes usually take effect within an hour
• What Joyous provides: one verification value that is unique to your domain (see below)

Before you start

1. Choose the sending domain. This is the domain in the From address of Joyous emails. We recommend a subdomain such as engage.yourcompany.com or cx.yourcompany.com: it keeps Joyous sending separate from your corporate mail. Your main domain works too.
2. Email Joyous the domain and the From address you want to use (for example engage@cx.yourcompany.com). The mailbox does not need to exist unless you want replies to reach it.
3. Joyous sends you a verification value that looks like mandrill_verify.xxxxxxxxxxxxxxxxxxxxxx. It is unique to your domain, so it can't be reused from another setup.

In the records below, replace <domain> with your chosen sending domain.

DNS records to add

Add these four records to the DNS for your sending domain. Enter every value exactly as shown.

Type	Name (host)	Value	What it does
TXT	<domain>	mandrill_verify.… (the value Joyous sent you)	Proves you own the domain
CNAME	mte1._domainkey.<domain>	dkim1.mandrillapp.com	DKIM signing key 1
CNAME	mte2._domainkey.<domain>	dkim2.mandrillapp.com	DKIM signing key 2
CNAME	bounce.<domain>	mandrillapp.com	Return path: handles bounces and passes SPF

Example for the sending domain engage.example.com, in a DNS zone for example.com. Most DNS providers want the host name without the zone, as shown here.

Type	Host	Value
TXT	engage	mandrill_verify.…
CNAME	mte1._domainkey.engage	dkim1.mandrillapp.com
CNAME	mte2._domainkey.engage	dkim2.mandrillapp.com
CNAME	bounce.engage	mandrillapp.com

Notes:

• The TXT record is added alongside any TXT records already on that name, including SPF. It doesn't replace them.
• Mandrill checks each value exactly. Point the CNAMEs directly at the mandrillapp.com names above, not through another record of your own.
• If you use Cloudflare, set the CNAME records to DNS only (grey cloud), not proxied.

Optional: list Joyous in your SPF record

This step is not needed for delivery. SPF is checked on the bounce.<domain> return path, which passes through the CNAME above.

If your policy requires every sender to be listed in SPF, add this to the SPF record of your sending domain, before the final ~all or -all:

include:_spf.joyoushq.com

For a sending domain that has no SPF record and sends no other mail, the complete record would be:

v=spf1 include:_spf.joyoushq.com ~all

_spf.joyoushq.com lists only Joyous's dedicated sending IPs. It costs one DNS lookup and contains no further lookups. SPF allows at most 10 lookups per record, so check your total before adding it: going over breaks SPF for all mail from that domain.

After you add the records

Let Joyous know once the records are in. We then:

1. Check that Mandrill shows your domain as Verified, DKIM valid and Authenticated.
2. Set up bounce.<domain> as the return-path domain for your emails.
3. Send a test email and check its authentication results.

Setup is complete when a test email shows all of these:

Check	Expected result
SPF	pass, for bounce.<domain>
DKIM	pass, with d=<domain>
DMARC	pass, for your From domain

To check a message yourself in Gmail, open it and choose Show original. The SPF, DKIM and DMARC results are listed at the top.

Troubleshooting and FAQ

Mandrill shows a DKIM error, but the records resolve. Mandrill compares each CNAME value exactly. Check the value is dkim1.mandrillapp.com or dkim2.mandrillapp.com directly, with no intermediate record, and no typo or trailing text added by your DNS provider.

My DNS provider says a record already exists for bounce.<domain>. A CNAME can't share a name with any other record. Remove the existing record if it's unused, or tell us and we'll use a different name, such as mail.<domain>.

Do we need to change our DMARC policy? No. Joyous emails pass DMARC through the DKIM signature for your domain, whatever your policy is.

Can we point the records at a Joyous hostname instead of Mandrill? No. Mandrill only accepts its own values, so records routed through another name fail its checks.

What are we authorising? Only Joyous's Mandrill account can send as your domain: Mandrill signs for a domain only after it has been verified in that account. The return-path CNAME affects only the bounce.<domain> name. Your main SPF record, MX records and other mail stay as they are.

Will this change if Joyous's sending IPs change? No. The records point to Mandrill, so IP changes need nothing from you. If you added the optional SPF include, Joyous updates _spf.joyoushq.com itself.