Mail System

CorePanel includes a complete email stack designed for reliability, security, and high deliverability. This document provides technical details about the mail system architecture and configuration.

Mail Stack Components

CorePanel’s mail system is built on industry-standard components:

Component	Role
Postfix	SMTP server (sending/receiving mail)
Dovecot	IMAP/POP3 server and LMTP delivery
Rspamd	Spam filtering and DKIM signing
corepanel-auth	Authentication broker

Architecture Overview

                    ┌─────────────────┐
    Incoming Mail   │                 │
    ───────────────►│     Postfix     │
                    │   (SMTP MTA)    │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │     Rspamd      │
                    │  (filtering)    │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  Dovecot LMTP   │◄──── User Access (IMAP/POP3)
                    │   (delivery)    │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │ corepanel-auth  │◄──── Authentication
                    │   (broker)      │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │ corepanel-core  │◄──── User/Mailbox Database
                    │   (SQLite)      │
                    └─────────────────┘

Email Account Management

Account Creation

When a mailbox is created through the CorePanel interface or API, the following process occurs:

1. corepanel-api receives the creation request
2. corepanel-core validates the domain ownership and quota limits
3. corepanel-core stores the mailbox metadata in SQLite
4. corepanel-core syncs the mailbox to Postfix lookup database
5. Dovecot creates the maildir structure on first delivery

# Mailbox directory structure
/home/{account}/mail/{domain}/{localpart}/
├── cur/      # Read messages
├── new/      # Unread messages
└── tmp/      # Temporary storage during delivery

Mailbox Data Model

Each mailbox stores the following information:

Field	Description
Localpart	Email local part (e.g., “user”)
Username	Full email address (e.g., “user@example.com”)
Password	bcrypt hash
QuotaMB	Storage quota in megabytes
LinuxUID/GID	OS-level user/group for mail delivery
HomeDir	Account home directory
Active	Enable/disable flag

Quota Management

Each mailbox has configurable storage quotas stored in the CorePanel database. Dovecot queries these quotas through the corepanel-auth service in real-time, ensuring:

• Accurate quota enforcement during delivery
• Instant quota updates without service restarts
• Per-mailbox and per-domain quota limits

The corepanel-auth Service

The corepanel-auth service is a critical component that acts as an authentication broker between mail services and the CorePanel database.

Why corepanel-auth?

Traditional mail setups require direct database queries from Postfix and Dovecot. This approach has several drawbacks:

• Database credentials exposed in multiple config files
• No centralized authentication logic
• Difficult to implement custom authentication rules
• Complex query configuration in mail services

corepanel-auth solves these problems by providing a unified authentication endpoint.

How It Works

┌──────────────┐     checkpassword protocol   ┌─────────────────┐
│   Dovecot    │ ───────────────────────────►│                 │
└──────────────┘                             │  corepanel-auth │
                                             │                 │
┌──────────────┐     socketmap lookups       │   (JSON-RPC)    │
│   Postfix    │ ───────────────────────────►│                 │
└──────────────┘                             └────────┬────────┘
                                                      │
                                             ┌────────▼────────┐
                                             │  corepanel-core │
                                             │    (database)   │
                                             └─────────────────┘

Authentication Flow

1. User attempts IMAP/SMTP login
2. Dovecot calls the checkpassword helper binary
3. Helper connects to corepanel-auth via Unix socket
4. corepanel-auth queries corepanel-core via JSON-RPC (core.AuthenticateMailUser)
5. Response returns UID, GID, home directory, maildir path, and quota
6. Helper translates response into Dovecot environment variables

Postfix Integration

Postfix uses socketmap lookups to query corepanel-auth for:

Lookup	Purpose
domains	Check if domain is configured for mail
alias	Get destination for email aliases

Socket Locations

/var/run/corepanel/corepanel-mail-auth.sock

Service Dependencies

Always ensure corepanel-auth and corepanel-core are running before starting Dovecot or Postfix. The services depend on authentication being available.

SPF (Sender Policy Framework)

SPF is a DNS-based email authentication method that specifies which mail servers are authorized to send email on behalf of your domain.

How SPF Works

1. Sending server connects to receiving server
2. Receiving server checks the sender’s domain SPF record
3. SPF record lists authorized IP addresses/hostnames
4. If sender’s IP matches, email passes SPF check

SPF Record Format

A typical SPF record looks like:

v=spf1 a mx ip4:SERVER_IP ~all

Mechanism	Description
v=spf1	SPF version identifier
a	Allow the domain’s A record IP
mx	Allow the domain’s MX server IPs
ip4:	Allow specific IPv4 addresses
~all	Soft fail for unauthorized senders

SPF in CorePanel

CorePanel automatically creates SPF records when a domain is added. The default record is:

example.com. IN TXT "v=spf1 a mx ~all"

This default configuration:

• Allows the domain’s A record IP to send mail
• Allows the domain’s MX servers to send mail
• Uses soft fail (~all) for other sources

The system verifies SPF validity by:

1. Performing DNS TXT lookup on the domain
2. Searching for records starting with v=spf1
3. Displaying the status in the domain’s mail configuration

SPF Best Practices

• Use ~all (soft fail) during initial setup, switch to -all (hard fail) once verified
• Keep records under 10 DNS lookups to avoid SPF permerror
• Include third-party senders (e.g., include:_spf.google.com for Google Workspace)

SPF Limitations

SPF only validates the envelope sender (MAIL FROM), not the header From address. Use DKIM and DMARC for complete email authentication.

DKIM (DomainKeys Identified Mail)

DKIM adds a cryptographic signature to outgoing emails, allowing receiving servers to verify that the message was sent by an authorized server and wasn’t modified in transit.

How DKIM Works

1. Key Generation: CorePanel generates a 2048-bit RSA key pair per domain
2. DNS Publication: Public key is published as a TXT record
3. Message Signing: Rspamd signs outgoing emails with the private key
4. Verification: Receiving servers verify signatures using the public key

DKIM Key Management

CorePanel uses Rspamd for DKIM key generation and signing:

Setting	Value
Selector	cp1
Key size	2048-bit RSA
Key location	/var/lib/rspamd/dkim/

DKIM Signing Process

┌─────────────────┐
│  Outgoing Email │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌──────────────────┐
│    Postfix      │────►│     Rspamd       │
│                 │     │    (milter)      │
└─────────────────┘     └────────┬─────────┘
                                 │
                        ┌────────▼─────────┐
                        │  Private Key     │
                        │  (per domain)    │
                        └────────┬─────────┘
                                 │
                        ┌────────▼─────────┐
                        │ DKIM-Signature   │
                        │ header added     │
                        └──────────────────┘

DKIM DNS Record

CorePanel generates DKIM public keys with the selector cp1:

cp1._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=MIIBIjANBgkqh..."

Tag	Description
v=DKIM1	DKIM version
k=rsa	Key type (RSA)
p=	Base64-encoded public key

Setting Up DKIM

CorePanel handles DKIM setup automatically:

1. Key Generation: When a domain is added, CorePanel generates the DKIM key pair
2. DNS Publication: The public key is automatically published to the DNS zone at cp1._domainkey.yourdomain.com
3. Signing Activation: Rspamd begins signing outgoing mail immediately

No manual DNS configuration is required since CorePanel manages the DNS zones.

Verifying DKIM Setup

Send a test email to a Gmail address and check the headers:

Authentication-Results: mx.google.com;
       dkim=pass header.d=example.com header.s=cp1;
       spf=pass smtp.mailfrom=user@example.com

DKIM Key Rotation

CorePanel supports DKIM key rotation with incremental selectors to maintain email deliverability during the transition period.

Why Rotate DKIM Keys?

• Security: Periodic key rotation limits the impact of potential key compromise
• Compliance: Some security policies require regular cryptographic key rotation
• Key Size Updates: Upgrade from older 1024-bit keys to 2048-bit keys

How Key Rotation Works

When you rotate a DKIM key through the CorePanel interface:

1. New Selector Generated: A new selector is created incrementally (cp1 → cp2 → cp3…)
2. Key Pair Created: A new 2048-bit RSA key pair is generated
3. Selector Maps Updated: Rspamd is configured to use the new selector for signing
4. DNS Record Added: If DNS is managed by CorePanel, the new DKIM record is automatically added
5. Grace Period: The old key remains valid for 7 days

Selector Mapping

CorePanel uses rspamd’s selector_map and path_map configuration to support different selectors per domain:

/var/lib/rspamd/dkim/selectors.map    # Maps domains to selectors
/var/lib/rspamd/dkim/paths.map        # Maps domains to key file paths

Example content:

selectors.map

example.com cp2
other.com cp1

# paths.map
example.com /var/lib/rspamd/dkim/example.com.cp2.key
other.com /var/lib/rspamd/dkim/other.com.cp1.key

Key File Naming

DKIM keys are stored with the selector in the filename:

/var/lib/rspamd/dkim/
├── example.com.cp1.key    # Old key (expired)
├── example.com.cp1.txt    # Old public key record
├── example.com.cp2.key    # Current active key
└── example.com.cp2.txt    # Current public key record

Grace Period Cleanup

A daily job (4:00 AM server time) automatically cleans up expired selectors:

1. Removes key files from /var/lib/rspamd/dkim/
2. Deletes the DNS record (if DNS is managed)
3. Removes the selector from the database

Rotating keys

DKIM key rotation is triggered from the panel (the domain’s mail configuration). There is no corepanel CLI subcommand for DKIM. Programmatically, rotation is the core.RotateDKIMKey JSON-RPC method on corepanel-core, and the active selectors for a domain are available through sys.ListDKIMSelectors on corepanel-sys — the same methods the panel uses. From a shell you can still inspect the result directly with the selector maps and dig (see below).

Troubleshooting Key Rotation

Check active selector:

cat /var/lib/rspamd/dkim/selectors.map | grep example.com

Verify new DKIM record:

dig +short TXT cp2._domainkey.example.com

Check rspamd configuration:

cat /etc/rspamd/local.d/dkim_signing.conf

View rspamd logs for signing issues:

journalctl -u rspamd | grep -i dkim

Grace Period

During the 7-day grace period after rotation, both the old and new selectors have valid DNS records. This ensures emails signed with the old key before rotation can still be verified by receiving servers.

Mail Mode Detection

CorePanel automatically detects the mail capabilities for each domain:

Mode	Description	Requirements
None	No mail capability	-
Inbound	Can receive mail	MX points to server
Outbound	Can send mail	DKIM valid or DNS managed
Full	Send and receive	MX + DKIM configured

The system performs the following DNS checks:

• MX Records: Verifies MX points to server hostname or IP
• DKIM Record: Validates cp1._domainkey TXT record matches expected key
• SPF Record: Detects presence of v=spf1 record

TLS Certificate Management

Postfix TLS

Postfix uses certificates in the following priority:

1. Exact hostname certificate
2. Wildcard certificate for parent domain
3. System default certificate

Dovecot TLS

Dovecot supports SNI (Server Name Indication) for multiple certificates:

• Certificates are scanned from /var/lib/cp-sys/ssl/certs/
• Configuration generated at /etc/dovecot/conf.d/99-corepanel-ssl.conf
• Supports per-domain certificates with automatic fallback

Troubleshooting

Common Issues

Mail not sending/receiving:

# Check service status
systemctl status postfix dovecot rspamd corepanel-auth

# Check mail logs
tail -f /var/log/maillog

Authentication failures:

# Check auth socket exists and has correct permissions
ls -la /var/run/corepanel/corepanel-mail-auth.sock

# Check corepanel-auth logs
journalctl -u corepanel-auth -f

SPF/DKIM failures:

# Test SPF record
dig +short TXT example.com | grep spf

# Test DKIM record
dig +short TXT cp1._domainkey.example.com

Mail Queue Management

# View mail queue
postqueue -p

# Flush the queue
postqueue -f

# Delete all queued mail (use with caution)
postsuper -d ALL

Additional Resources

• Postfix Documentation
• Dovecot Wiki
• Rspamd Documentation
• SPF Record Syntax