← Back to ColdFusion Administrator Reference

Settings - Mail

Configure SMTP servers, mail spooling, and email delivery settings

Last updated: October 27, 20256 min read

Overview

The Mail Settings page controls how ColdFusion sends email via the cfmail tag. You can configure multiple SMTP servers for redundancy, set up mail spooling for asynchronous delivery, configure authentication and encryption, and manage mail queue behavior. Proper configuration ensures reliable email delivery and optimal performance.

SMTP Server Configuration

Configure primary and backup SMTP servers for email delivery.

Mail Server (SMTP)

PurposePrimary SMTP server hostname or IP address
DefaultEmpty (must be configured)
Examplesmtp.example.com, smtp.gmail.com, mail.privateemail.com
RecommendationUse internal relay server for production environments
Multiple Servers: Add multiple servers for failover redundancy to ensure email delivery even if primary server is unavailable.

Server Port

PurposeSMTP port number
Default25 (standard SMTP)
Common Ports25 - Standard SMTP (often blocked by ISPs)
587 - Submission port with STARTTLS (recommended)
465 - SMTPS (implicit SSL/TLS, legacy)
2525 - Alternative submission port
RecommendationUse port 587 with TLS for secure, reliable delivery

Username & Password

PurposeSMTP authentication credentials
DefaultEmpty (anonymous)
RecommendationAlways use authentication in production
FormatUsually email address or username
Security: Password is encrypted in configuration files. Use application-specific passwords when available. For Gmail/Google Workspace, use App Passwords, not account password.

Use SSL/TLS Connection

PurposeEnable encryption for SMTP connection
DefaultDisabled
RecommendationAlways enable for security
OptionsTLS (STARTTLS): Upgrades plain connection to encrypted (port 587)
SSL: Encrypted from start (port 465)
ImpactProtects credentials and email content in transit

Verify Connection

PurposeTest SMTP server connectivity and authentication
UseClick after configuring server settings
ValidatesHostname resolution, port connectivity, authentication
Best Practice: Always verify before saving configuration to ensure settings are correct.

Mail Spool Settings

Configure asynchronous email processing and queue management.

Enable Mail Spool

PurposeProcess email asynchronously via background thread
DefaultEnabled (recommended)
RecommendationAlways enable for production environments
BenefitsFaster page response times (email queued, not sent during request)
Automatic retry on delivery failures
Better handling of SMTP server issues
Rate limiting and throttling capabilities
ImpactEmail delivery is delayed by spool interval (typically seconds)

Spool Interval (seconds)

PurposeHow often ColdFusion processes queued emails
Default15 seconds
RecommendationMost apps: 5-15 seconds
High Volume: 1-5 seconds
Low Volume: 30-60 seconds
Trade-offLower interval = faster delivery but more processing overhead

Maximum Number of Messages to Deliver Per Spool Interval

PurposeLimits emails sent per interval to prevent overload
Default10
RecommendationSet based on mail server capabilities and volume
High VolumeIncrease to 50-100 if mail server can handle it
Rate Limiting: Use to comply with SMTP provider rate limits. For example, SendGrid limits to 100/second, so set accordingly based on your spool interval.

Spool Mail Directory

PurposeFile system location for queued emails
Defaultcfusion/mail/spool
RecommendationUse default unless you have specific requirements
ConsiderationsMust have read/write permissions, adequate disk space
Monitoring: Watch for growing queue indicating delivery issues. Allocate sufficient disk space for peak mail volumes.

Delivery Failure Settings

Control retry behavior and handling of failed email delivery.

Maximum Number of Delivery Attempts

PurposeHow many times to retry failed email delivery
Default3
Recommendation3-5 attempts
ImpactMore retries increase chance of delivery but consume resources
Retry TimingExponential backoff between attempts

Retry Interval (seconds)

PurposeWait time before retrying failed delivery
Default300 seconds (5 minutes)
Recommendation300-900 seconds (5-15 minutes)
PatternSubsequent retries wait longer (exponential backoff)
RationaleGives temporary SMTP issues time to resolve

Undelivered Message Directory

PurposeWhere to store emails that fail all delivery attempts
Defaultcfusion/mail/undelivr
RecommendationMonitor this directory regularly
Maintenance Required: Investigate patterns of undeliverable mail, periodically archive or delete old messages, and set up monitoring alerts for accumulation.

Advanced Settings

Configure additional mail server options and logging.

Default Mail Server

Purpose
Primary server used when multiple servers are configured
Behavior
Falls back to backup servers if primary fails
Recommendation
Set your most reliable server as default

Enable Backup Mail Server

Purpose
Add redundant SMTP servers for failover
Recommendation
Configure backup server for high-availability

Use different providers/infrastructure for true redundancy. Example: Primary = internal relay, Backup = external service (SendGrid, SES)

Mail Character Set

Default
UTF-8
Recommendation
Always use UTF-8 for international character support

Default character encoding for email messages. Can be overridden per-message in cfmail tag.

Sign Messages

Default
Disabled
Use Case
Required for certain compliance scenarios
Requirement
Must configure keystore and certificate

Digitally sign outgoing emails with certificate for compliance and security.

Mail Logging

Default
Error level
Recommendation
Information for production, Debug for troubleshooting
Location
cfusion/logs/mail.log

Log mail operations including SMTP transactions, delivery attempts, and errors.

Popular SMTP Provider Settings

Quick reference for common email service provider configurations.

Gmail / Google Workspace

Server
smtp.gmail.com
Port
587 (TLS enabled)
Authentication
Email address and App Password
Limit
500/day (Gmail), higher for Workspace

Must use App Passwords, not regular password. Enable "Less secure app access" if needed.

Microsoft 365 / Outlook.com

Server
smtp-mail.outlook.com or smtp.office365.com
Port
587 (TLS enabled)
Authentication
Full email address and password
Limit
300/day (Outlook), 10,000/day (M365)

SendGrid

Server
smtp.sendgrid.net
Port
587 or 2525 (TLS enabled)
Username
apikey (literal string)
Password
Your SendGrid API key
Limit
100/day free, 100/second paid

Amazon SES

Server
email-smtp.us-east-1.amazonaws.com
Port
587 (TLS enabled)
Credentials
SMTP username/password from SES console

Region-specific endpoint. Start in sandbox mode, request production access.

Mailgun

Server
smtp.mailgun.org
Port
587 (TLS enabled)
Username
postmaster@your-domain.mailgun.org
Password
SMTP password from Mailgun dashboard

Best Practices

Production Environment

  • Always enable mail spooling for async delivery
  • Configure backup SMTP server for redundancy
  • Use TLS encryption for all SMTP connections
  • Set spool interval based on volume (5-15 seconds typical)
  • Monitor undelivered mail directory for delivery issues
  • Configure appropriate rate limiting for your SMTP provider
  • Use dedicated SMTP service (SendGrid, SES) for high volume
  • Implement SPF, DKIM, and DMARC records for deliverability
  • Monitor mail.log for errors and delivery failures

Development Environment

  • Use mail capture tools (MailHog, Papercut) to avoid sending real emails
  • Configure test SMTP server separate from production
  • Set longer spool intervals to reduce processing overhead
  • Enable debug logging to troubleshoot issues

Security Considerations

  • Always use authentication - never allow anonymous relay
  • Enable TLS/SSL encryption to protect credentials
  • Use app-specific passwords instead of primary account passwords
  • Restrict SMTP relay to authorized IP addresses when possible
  • Implement rate limiting to prevent email flooding
  • Validate email addresses to prevent injection attacks
  • Monitor for unusual sending patterns indicating compromise
  • Rotate SMTP credentials periodically

Performance Tuning

  • Enable mail spooling to prevent cfmail from blocking requests
  • Adjust spool interval based on volume and latency requirements
  • Increase messages per interval for high-volume applications
  • Use multiple SMTP servers to distribute load
  • Monitor spool directory size - large queues indicate issues
  • Consider external mail service for bulk sending

Common Issues and Solutions

Email Not Sending

  • Symptom: cfmail executes but emails never arrive
  • Check: SMTP server settings, authentication, port accessibility
  • Solution: Use "Verify Connection" to test configuration
  • Firewall: Ensure SMTP ports (587, 465, 25) are not blocked
  • Logs: Check mail.log for connection errors

Authentication Failed

  • Symptom: "Authentication failed" error in mail.log
  • Gmail: Use App Password, enable "Less secure app access"
  • Office 365: Verify SMTP AUTH is enabled for mailbox
  • Solution: Double-check username, password, and authentication method

Emails Going to Spam

  • Symptom: Emails delivered but marked as spam
  • SPF Record: Add SMTP server to SPF record
  • DKIM: Configure DKIM signing for authentication
  • DMARC: Implement DMARC policy
  • Content: Avoid spam trigger words, include unsubscribe link
  • Reputation: Use reputable SMTP service, warm up IP address

Spool Queue Growing

  • Symptom: Thousands of files in spool directory
  • Cause: SMTP server unavailable or rate limiting too aggressive
  • Solution: Check SMTP connectivity, increase messages per interval
  • Emergency: Temporarily disable rate limiting to clear backlog
  • Prevention: Monitor queue depth, alert on growth

Slow Page Performance

  • Symptom: Pages with cfmail tag load slowly
  • Cause: Mail spooling disabled, sending synchronously
  • Solution: Enable mail spooling for async delivery
  • Alternative: Use cfthread for immediate sending without blocking

Connection Timeout

  • Symptom: "Connection timeout" errors
  • Firewall: SMTP port blocked by firewall or security group
  • Network: Network connectivity issues
  • Solution: Verify port accessibility using telnet or nc
  • Test: telnet smtp.example.com 587

Monitoring and Maintenance

Daily Monitoring

  • Check spool directory size - should be near empty
  • Review mail.log for errors
  • Monitor undelivered directory for failed messages
  • Track email delivery metrics (sent, failed, bounced)

Weekly Maintenance

  • Review undelivered messages, investigate patterns
  • Archive or delete old mail.log files
  • Check for mail server connectivity issues
  • Verify backup SMTP server is functional

Alerts to Configure

  • Spool queue exceeds 100 messages
  • Undelivered directory exceeds 50 messages
  • SMTP connection failures exceed threshold
  • Mail.log shows authentication failures

Related Resources

Performance Optimization FrameworkEmail delivery and SMTP optimization strategiesServer Settings - SettingsGeneral server configuration and request handlingColdFusion Administrator ReferenceComplete administrator guide and settings reference