Troubleshooting

Email authentication is critical for successful email delivery. This guide helps you troubleshoot common SPF, DKIM, and DMARC issues with Email Service.

Having multiple SPF records on your domain is not allowed and will prevent Email Service from working properly. If your domain has multiple SPF records:

1. Log in to the Cloudflare dashboard, select your account and domain, then go to DNS > Records.

   Go to Records ↗

2. Look for multiple TXT records starting with v=spf1.

3. Delete the incorrect SPF record.

4. Ensure you have the correct SPF records:

   • For Email Routing (root domain): v=spf1 include:_spf.mx.cloudflare.net ~all
   • For Email Sending (cf-bounce subdomain): v=spf1 include:_spf.mx.cloudflare.net ~all

If you are unsure which SPF record is the correct one to keep, you can remove all of them and let Cloudflare regenerate the required records:

1. In DNS > Records, delete every TXT record starting with v=spf1 on the affected name.
2. Go to Compute > Email Service and re-onboard or re-enable the affected service. Cloudflare adds the correct SPF record back automatically.

If emails are being rejected due to SPF failures:

1. Log in to the Cloudflare dashboard, select your account and domain, then go to DNS > Records.

   Go to Records ↗

2. Add TXT records for the appropriate service:

   • For Email Routing: Name: @ (root domain), Content: v=spf1 include:_spf.mx.cloudflare.net ~all
   • For Email Sending: Name: cf-bounce, Content: v=spf1 include:_spf.mx.cloudflare.net ~all

3. If you already have an SPF record on the root domain, modify it to include include:_spf.mx.cloudflare.net

Common SPF record syntax issues:

• Missing version: SPF records must start with v=spf1
• Multiple includes: Combine multiple services using separate include: statements
• Too many DNS lookups: SPF records are limited to 10 DNS lookups total
• Incorrect all mechanism: Use ~all (SoftFail) or -all (Fail), not +all

Correct format:

v=spf1 include:_spf.mx.cloudflare.net include:other-service.com ~all

Verify your SPF record is configured correctly:

dig TXT example.com +short | grep spf

Expected result should include:

"v=spf1 include:_spf.mx.cloudflare.net ~all"

Email Service automatically generates DKIM keys for your domain, but the DNS records must be properly configured. Email Sending and Email Routing use separate DKIM selectors:

1. In the Cloudflare dashboard ↗︎, go to Compute > Email Service.
2. Select your domain.
3. Check the Settings page for the appropriate service:
   • Email Sending: Go to Email Sending > Settings to find the sending DKIM record (cf-bounce._domainkey).
   • Email Routing: Go to Email Routing > Settings to find the routing DKIM record (cf2024-1._domainkey).
4. Copy the DKIM record details.
5. Go to DNS > Records and add the DKIM TXT record with the correct selector name and public key.

If you need to rotate DKIM keys:

1. Contact Cloudflare support to request key rotation.
2. Update your DNS records with the new DKIM key when provided.
3. Monitor email delivery during the transition period.

Verify your DKIM records are configured correctly:

# Check Email Sending DKIM
dig TXT cf-bounce._domainkey.example.com +short

# Check Email Routing DKIM
dig TXT cf2024-1._domainkey.example.com +short

Expected result for either:

"v=DKIM1; h=sha256; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."

If DKIM validation is failing:

1. Verify the DKIM record exists in DNS
2. Check that the record name matches the correct selector:
   • Email Sending: cf-bounce._domainkey.yourdomain.com
   • Email Routing: cf2024-1._domainkey.yourdomain.com
3. Ensure there are no extra spaces or characters in the DNS record
4. Wait for DNS propagation (up to 48 hours)
5. Use online DKIM validators to test your configuration

While not required, DMARC significantly improves email deliverability:

1. Go to DNS > Records in the Cloudflare dashboard.

   Go to Records ↗

2. Add a TXT record:

   • Name: _dmarc
   • Content: v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com

If a strict DMARC policy is causing delivery issues:

1. Start with a lenient policy: p=none (monitor only)
2. Monitor DMARC reports for several weeks
3. Gradually increase strictness: p=quarantine then p=reject
4. Ensure both SPF and DKIM are properly aligned

DMARC requires either SPF or DKIM alignment:

SPF alignment: The domain in the Mail From header must align with the domain in the From header DKIM alignment: The DKIM signature domain must align with the domain in the From header

Email Service ensures proper alignment automatically.

Verify your DMARC record:

dig TXT _dmarc.example.com +short

Example result:

"v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com; ruf=mailto:dmarc@example.com; sp=quarantine"

This error occurs when passing ArrayBuffer content in attachment fields during local development with wrangler dev. The local email binding simulator cannot serialize ArrayBuffer values.

Solution: Deploy your Worker with npx wrangler deploy and test binary attachments (images, PDFs) against the deployed version. String content for text-based attachments works normally in local development. Refer to local development for email sending for more details.

If emails are going to spam folders:

1. Check authentication: Ensure SPF, DKIM, and DMARC are properly configured
2. Domain reputation: New domains may have lower reputation initially
3. Content quality: Avoid spam trigger words and excessive HTML formatting
4. Sender reputation: Monitor bounce rates and complaint rates
5. List hygiene: Remove bounced and invalid email addresses

To reduce bounce rates:

1. Validate email addresses: Use real-time validation
2. Maintain clean lists: Remove hard bounces immediately
3. Monitor feedback loops: Subscribe to ISP feedback loops
4. Gradual warm-up: For new domains, start with small volumes

Each sending domain has a Drop suppressed recipients setting. The setting is off by default.

When the setting is off, the REST API returns 400, the Workers binding throws E_RECIPIENT_SUPPRESSED, and SMTP rejects the message. Any suppressed recipient causes the send to fail.

When the setting is on, Email Service removes suppressed recipients and processes the remaining recipients. If none remain, SMTP may return 250 2.0.0 Ok without a Message-ID and deliver nothing.

To investigate a suppressed recipient:

Expired entries stop appearing in the public list after their expires_at timestamp passes. Delivery enforcement can take additional time to stop.

Updates and deletions also propagate asynchronously. The management list and delivery enforcement can briefly differ.

To investigate delayed enforcement:

Bounce suppressions are created through background delivery processing. Messages already in progress can bounce before a new suppression takes effect.

Complaint suppressions appear after Cloudflare receives and validates the provider report. The provider determines when that report arrives.

Not every failure results in a suppression. Email Service creates automatic entries only for eligible recipient-side failures. Sender authentication, sender reputation, and unrelated infrastructure failures do not suppress the recipient. Check Email sending logs for the specific failure.

Different ISPs have specific requirements:

• Gmail: Requires strong domain reputation and authentication
• Outlook/Hotmail: Sensitive to content and sender reputation
• Yahoo: Strict DMARC enforcement
• Corporate: Often have strict filtering rules

Use these tools to validate your email authentication setup:

1. MX Toolbox: Check SPF, DKIM, and DMARC records
2. DMARC Analyzer: Validate DMARC policy and alignment
3. Mail Tester: Test email deliverability and authentication
4. Google Admin Toolbox: Google's email authentication checker

If you continue to experience authentication issues:

1. Check the Email Service analytics for delivery metrics
2. Review bounce messages for specific error codes
3. Contact Cloudflare Support ↗︎ with:
   • Domain name
   • Example email headers
   • Specific error messages
   • SPF, DKIM, and DMARC record configurations