Connecting a Custom Domain to Icewarp (self-hosted)

Overview

After installing IceWarp, you need to configure DNS records to ensure email delivery, autodiscovery, and other services work correctly. This guide will help you set up the necessary DNS records for your domain.

Prerequisites

• Your domain name (e.g., example.com)
• Your IceWarp server's public IP address or hostname (e.g., mail.example.com)
• Access to your domain's DNS management panel (through your domain registrar or DNS provider)

Required DNS Records

Below is a complete example configuration. Replace example.com with your actual domain name and mail.example.com with your IceWarp server's hostname.

Example DNS Records

Domain: example.com

# A Record - Points your mail subdomain to your server IP
mail              IN A     192.0.2.10
# MX Record - Tells other mail servers where to deliver email
@                 IN MX    10 mail.example.com.
# Autodiscover - Helps email clients automatically configure settings
autodiscover      IN CNAME mail.example.com.
# SPF Record - Prevents email spoofing
@                 IN TXT   "v=spf1 mx ~all"
# DKIM Record - Email authentication (generate in IceWarp admin)
default._domainkey IN TXT  "v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY_HERE"
# DMARC Record - Email policy and reporting
_dmarc            IN TXT   "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com"
# SRV Records (optional) - Enable automatic service discovery for various protocols
_autodiscover._tcp     IN SRV 1 5 443 mail.example.com.
_caldav._tcp           IN SRV 1 5 80 mail.example.com.
_caldavs._tcp          IN SRV 1 5 443 mail.example.com.
_carddav._tcp          IN SRV 1 5 80 mail.example.com.
_carddavs._tcp         IN SRV 1 5 443 mail.example.com.
_ischedule._tcp        IN SRV 1 5 80 mail.example.com.
_ischedules._tcp       IN SRV 1 5 443 mail.example.com.
_xmpp-client._tcp      IN SRV 1 5 5222 mail.example.com.
_xmpp-server._tcp      IN SRV 1 5 5269 mail.example.com.

Step-by-Step DNS Setup

Step 1: Create the A Record

The A record points your mail subdomain to your server's IP address.

What to create:

• Type: A
• Name/Host: mail
• Value/Points to: Your server's IP address (e.g., 192.0.2.10)
• TTL: 3600 (or 1 hour)

Example: mail.example.com → 192.0.2.10

Step 2: Create the MX Record

The MX (Mail Exchange) record tells other mail servers where to deliver email for your domain.

What to create:

• Type: MX
• Name/Host: @ (represents your root domain)
• Priority: 10
• Value/Points to: mail.example.com
• TTL: 3600

Important: The priority value determines which server to use first if you have multiple MX records. Lower numbers = higher priority.

Step 3: Create Autodiscover CNAME

This helps email clients automatically configure connection settings.

What to create:

• Type: CNAME
• Name/Host: autodiscover
• Value/Points to: mail.example.com

• TTL: 3600

   

Step 4: Configure SPF Record

SPF (Sender Policy Framework) helps prevent email spoofing by specifying which servers can send email for your domain.

What to create:

• Type: TXT
• Name/Host: @ (root domain)
• Value: v=spf1 mx ~all
• TTL: 3600

SPF Record Explanation:

• v=spf1 - SPF version 1
• mx - Allow servers listed in MX records to send email
• ~all - Soft fail for all other servers (mark as suspicious but deliver)

For stricter policy, use -all instead of ~all (hard fail = reject).

Step 5: Configure DKIM Record

DKIM (DomainKeys Identified Mail) adds a digital signature to your emails.

First, generate the DKIM key in IceWarp:

1. Log into IceWarp Administration Console
2. Navigate to System → Domains → [Your Domain]
3. Go to Security → DKIM
4. Click Generate to create a new key
5. Copy the public key that appears

Then create the DNS record:

• Type: TXT
• Name/Host: default._domainkey
• Value: v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY_HERE (paste the key you copied)

• TTL: 3600

   

Step 6: Configure DMARC Record

DMARC (Domain-based Message Authentication) tells receiving servers what to do with emails that fail SPF or DKIM checks.

What to create:

• Type: TXT
• Name/Host: _dmarc
• Value: v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com
• TTL: 3600

DMARC Policy Options:

• p=none - Monitor only (recommended for initial setup)
• p=quarantine - Mark suspicious emails as spam
• p=reject - Reject emails that fail authentication

Note: Replace dmarc@example.com with an email address where you want to receive DMARC reports.

Step 7: Create SRV Records

SRV records enable automatic service discovery for calendars, contacts, and messaging.

These records are optional.

For each SRV record, you'll need:

• Type: SRV
• Name/Host: The service name (e.g., _autodiscover._tcp)
• Priority: 1
• Weight: 5
• Port: The service port (varies by service - see table below)
• Target: mail.example.com
• TTL: 3600

SRV Records Port Reference:

Note: Some DNS providers have different formats for entering SRV records. You may need to enter them as:

Service: _autodiscover

Protocol: _tcp

Priority: 1

Weight: 5

Port: 443

Target: mail.example.com

DNS Provider-Specific Notes

Common DNS Providers

Different DNS providers have different interfaces. Here are some tips:

Cloudflare:

• Very user-friendly interface
• Automatically adds the domain to records
• For MX records, make sure "Proxy status" is set to "DNS only" (gray cloud)

GoDaddy:

• Use @ for root domain
• Enter priority before the mail server for MX records
• SRV records have a separate form with individual fields

Namecheap:

• @ represents root domain
• Mail server names should end with a dot (e.g., mail.example.com.)
• TTL is usually set automatically

cPanel/WHM:

• Use the "Zone Editor" or "Advanced DNS Zone Editor"
• Most fields are straightforward
• Make sure to click "Save" after each record

Verification

After creating all DNS records, verify they're working correctly:

1. Check DNS Propagation

Use online tools to verify your records:

• https://mxtoolbox.com
• https://dnschecker.org
• https://www.whatsmydns.net

Note: DNS changes can take 24-48 hours to fully propagate, though they often work within 1-2 hours.

2. Test Email Delivery

Send a test email to an external address (Gmail, Outlook, etc.) and check:

• Does it arrive in the inbox (not spam)?
• View the email headers to verify SPF, DKIM, and DMARC pass

3. Test Autodiscover

Try configuring an email client (Outlook, Thunderbird) using only your email address and password. If autodiscover works, it should configure automatically.

4. Verify Using Command Line

You can check DNS records using command-line tools:

# Check MX record
dig MX example.com

# Check A record
dig A mail.example.com

# Check SPF record
dig TXT example.com

# Check DKIM record
dig TXT default._domainkey.example.com

# Check SRV record
dig SRV _autodiscover._tcp.example.com

Troubleshooting

MX Record Not Working:

• Ensure the record points to a hostname (mail.example.com), not an IP address
• Check that the hostname has a corresponding A record
• Verify there are no typos in the domain name

Autodiscover Not Working:

• Check that the CNAME record is correct
• Verify SSL certificate covers autodiscover.example.com
• Some clients may need the SRV record as well

SPF Failures:

• Make sure the SPF record includes all servers that send email for your domain
• If using third-party services (e.g., Mailchimp), include their SPF records
• Only one SPF record is allowed per domain

DKIM Failures:

• Verify the public key was copied correctly (no extra spaces or line breaks)
• Check that the record name includes ._domainkey
• The key must match the private key stored in IceWarp

DNS Changes Not Taking Effect:

• Wait 24-48 hours for full propagation
• Clear your local DNS cache: ipconfig /flushdns (Windows) or sudo dscacheutil -flushcache (macOS)
• Try checking from a different network or using mobile data

Security Best Practices

• Use strict SPF policy (-all) once you've verified everything works
• Enable DKIM signing for all outbound emails
• Start DMARC with p=none to monitor, then gradually move to p=quarantine or p=reject
• Use DNSSEC if your DNS provider supports it for added security
• Regularly monitor DMARC reports to catch authentication issues

Additional Resources

• MXToolbox - DNS/Email Testing
• DMARC Analyzer Tools