SPF DNS Configuration for Custom Email Branding

When you configure custom email branding on your widgets to send emails from your own domain (e.g., [email protected]), you need to configure SPF (Sender Policy Framework) records in your DNS. This ensures that email providers like Gmail, Outlook, and others recognize that CaptainBook is authorized to send emails on your behalf.

What is SPF?

SPF (Sender Policy Framework) is a DNS-based email authentication protocol that helps prevent email spoofing and phishing attacks. It works by allowing domain owners to specify which mail servers are authorized to send emails on behalf of their domain.

When you publish an SPF record in your DNS, you're essentially telling email providers: "These specific mail servers are allowed to send emails from my domain." This helps protect your domain's reputation and ensures your emails are delivered successfully.

Why Do You Need SPF for Custom Email Branding?

When you set a custom sender email address in your widget branding settings, emails are sent through Mailgun (our email delivery service) but appear to come from your domain. Without proper SPF configuration:

Emails may be marked as spam or rejected by recipients' email providers
Email deliverability rates may decrease significantly
Your domain's reputation may be damaged if emails are consistently rejected
Recipients may see security warnings about unverified senders

By adding the correct SPF record, you authorize CaptainBook (via Mailgun) to send emails from your domain, which:

✅ Improves email deliverability
✅ Reduces the chance of emails being marked as spam
✅ Protects your domain's reputation
✅ Provides better email authentication

How to Add SPF Records

Step 1: Access Your DNS Settings

Log in to your domain registrar or DNS hosting provider (e.g., GoDaddy, Namecheap, Cloudflare, AWS Route 53)
Navigate to your DNS management section
Find the DNS records for your domain

Step 2: Locate Existing SPF Records

Before adding a new SPF record, check if you already have one. Look for a TXT record with a name of @ or your domain name (sometimes shown as blank or yourdomain.com).

Common SPF record formats you might see:

v=spf1 include:_spf.google.com ~all 
v=spf1 include:spf.protection.outlook.com ~all 
v=spf1 a mx ~all

Step 3: Add or Update Your SPF Record

If You Don't Have an SPF Record

Create a new TXT record with the following values:

Type: TXT
Name: @ (or your domain name, depending on your DNS provider)
Value: v=spf1 include:mailgun.org ~all
TTL: 3600 (or your provider's default)

If You Already Have an SPF Record

Important: You can only have one SPF record per domain. If you already have an SPF record, you must merge it with the CaptainBook include, not create a separate record.

Step 4: Merge Multiple SPF Records

If you have existing SPF records (for example, from Google Workspace, Microsoft 365, or other email services), you need to combine them into a single SPF record.

Example: Combining with Google Workspace

Before (existing SPF):

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

After (merged with CaptainBook):

v=spf1 include:_spf.google.com include:mailgun.org ~all

Example: Combining with Microsoft 365

Before (existing SPF):

v=spf1 include:spf.protection.outlook.com ~all

After (merged with CaptainBook):

v=spf1 include:spf.protection.outlook.com include:mailgun.org ~all

Example: Combining Multiple Services

Before (existing SPF):

v=spf1 include:_spf.google.com include:spf.protection.outlook.com ~all

After (merged with CaptainBook):

v=spf1 include:_spf.google.com include:spf.protection.outlook.com include:mailgun.org ~all

Step 5: Save and Wait for Propagation

Save your DNS changes
Wait for DNS propagation (usually 15 minutes to 48 hours, but often within 1-2 hours)
Verify your SPF record is active using an SPF checker tool (see "Verifying Your SPF Record" below)

Understanding SPF Record Components

Let's break down the SPF record syntax:

v=spf1 include:mailgun.org ~all

v=spf1 - The SPF version identifier (always required)
include:mailgun.org - Authorizes Mailgun (CaptainBook's email delivery service) to send emails for your domain
~all - The qualifier that tells email providers what to do with emails from unauthorized servers:
- ~all (soft fail) - Emails from unauthorized servers are accepted but may be marked as suspicious
- all (hard fail) - Emails from unauthorized servers are rejected (more strict)
- ?all (neutral) - No policy (not recommended)
- +all (pass all) - Allows all servers (not recommended for security)

We recommend using ~all for most cases as it provides a good balance between security and deliverability.

Common SPF Record Examples

Basic SPF (Only CaptainBook)

v=spf1 include:mailgun.org ~all

CaptainBook + Google Workspace

v=spf1 include:_spf.google.com include:mailgun.org ~all

CaptainBook + Microsoft 365

v=spf1 include:spf.protection.outlook.com include:mailgun.org ~all

CaptainBook + Google Workspace + Microsoft 365

v=spf1 include:_spf.google.com include:spf.protection.outlook.com include:mailgun.org ~all

CaptainBook + Custom Mail Server

v=spf1 a mx include:mailgun.org ~all

CaptainBook + Multiple Services

v=spf1 include:_spf.google.com include:spf.protection.outlook.com include:mail.zendesk.com include:mailgun.org ~all

Verifying Your SPF Record

After adding or updating your SPF record, verify it's working correctly:

Method 1: Online SPF Checker Tools

Use one of these free tools to verify your SPF record:

MXToolbox SPF Record Lookup: https://mxtoolbox.com/spf.aspx
SPF Record Checker: https://www.spf-record.com/
DMARC Analyzer: https://dmarcian.com/spf-survey/

Simply enter your domain name and the tool will show your current SPF record and any issues.

Method 2: Command Line (Advanced)

Using dig or nslookup:

# Using dig 
dig TXT yourdomain.com  

# Using nslookup 
nslookup -type=TXT yourdomain.com

Look for a TXT record starting with v=spf1.

What to Look For

✅ Good signs:

SPF record is found and includes include:mailgun.org
No syntax errors reported
Record is properly formatted

❌ Warning signs:

Multiple SPF records (you should only have one)
Syntax errors
Missing include:mailgun.org
SPF record too long (over 255 characters may cause issues)

Troubleshooting Common Issues

Issue: "Multiple SPF records found"

Problem: You have more than one SPF record in your DNS.

Solution: You can only have one SPF record per domain. Merge all your SPF includes into a single record. For example:

Wrong:

TXT @ "v=spf1 include:_spf.google.com ~all" 
TXT @ "v=spf1 include:mailgun.org ~all"

Correct:

TXT @ "v=spf1 include:_spf.google.com include:mailgun.org ~all"

Issue: "SPF record too long"

Problem: Your SPF record exceeds 255 characters, which can cause DNS issues.

Solution: Some DNS providers allow longer records, but if you're hitting limits, you may need to:

Remove unnecessary includes
Use IP addresses instead of includes (if applicable)
Contact your DNS provider for support

Issue: "SPF record not propagating"

Problem: Changes aren't showing up after several hours.

Solution:

Check your DNS provider's propagation time (usually 15 minutes to 48 hours)
Clear your local DNS cache: ipconfig /flushdns (Windows) or sudo dscacheutil -flushcache (Mac)
Try checking from a different network or use an online DNS checker
Verify you saved the changes correctly in your DNS provider's interface

Issue: "Emails still going to spam after adding SPF"

Problem: SPF alone may not be enough for optimal deliverability.

Solution: Consider also setting up:

DKIM (DomainKeys Identified Mail) - Adds a cryptographic signature to emails
DMARC (Domain-based Message Authentication, Reporting & Conformance) - Provides policy for handling emails that fail SPF/DKIM checks

These work together with SPF to provide comprehensive email authentication.

Best Practices

Always merge, never duplicate: Only one SPF record per domain
Use ~all for most cases: Provides good balance between security and deliverability
Test before going live: Verify your SPF record works before sending important emails
Keep it updated: If you add new email services, remember to update your SPF record
Monitor email deliverability: Keep an eye on bounce rates and spam complaints

Additional Resources

Need Help?

If you're experiencing issues setting up your SPF record or have questions about email branding configuration, please contact our support team. We're here to help ensure your emails are delivered successfully.