Mail Configuration

Overview

The Mail Configuration module allows you to set up and manage email delivery settings for your website. Configure SMTP servers, test email functionality, and ensure reliable email delivery for notifications, contact forms, password resets, and other system emails. This module supports multiple mail providers including Gmail, Outlook, SendGrid, Mailgun, and custom SMTP servers.

Accessing Mail Configuration

Navigation path: Dashboard > System Settings > General Settings > Mail Configuration
(Or direct link from Settings menu if available)
Required permission: system.settings

Key Features

• Multiple Mail Drivers: Support for SMTP, Sendmail, Mailgun, Amazon SES, and Postmark
• SMTP Configuration: Complete SMTP server settings including host, port, and encryption
• Credential Management: Secure storage of mail server credentials
• Test Email Functionality: Send test emails to verify configuration
• Common Provider Presets: Quick reference for popular email providers
• Encryption Support: TLS and SSL encryption options for secure email delivery
• From Address Configuration: Set default sender name and email address

Main Interface

SMTP Configuration Section

The main configuration form contains all necessary fields for setting up email delivery:

• Mail driver selection dropdown
• SMTP server details (host, port, encryption)
• Authentication credentials (username, password)
• From address and name settings

Test Email Section

A dedicated area for testing your email configuration:

• Email address input field
• Send test email button
• Real-time feedback on test results
• Success/error message display

Common SMTP Providers Reference

An informational panel displaying quick-reference settings for popular email providers:

• Gmail configuration
• Outlook/Office 365 settings
• SendGrid details
• Mailgun information

Common Tasks

Task 1: Configure Gmail SMTP

1. Navigate to Dashboard > System Settings > Mail Configuration
2. Set Mail Driver to SMTP
3. Enter the following settings:
   • Mail Host: smtp.gmail.com
   • Mail Port: 587
   • Encryption: Select TLS
   • Username: Your full Gmail address (e.g., yourname@gmail.com)
   • Password: Your Gmail app password (not your regular password)
   • From Address: Your Gmail address or verified sending address
   • From Name: Your website or organization name
4. Click Save Configuration
5. Use the test email feature to verify the setup

Note: Gmail requires an App Password for SMTP access. Generate one at: https://myaccount.google.com/apppasswords

Task 2: Configure Outlook/Office 365 SMTP

1. Navigate to Dashboard > System Settings > Mail Configuration
2. Set Mail Driver to SMTP
3. Enter the following settings:
   • Mail Host: smtp.office365.com
   • Mail Port: 587
   • Encryption: Select TLS
   • Username: Your full Office 365 email address
   • Password: Your Office 365 password
   • From Address: Your Office 365 email address
   • From Name: Your website or organization name
4. Click Save Configuration
5. Send a test email to verify

Task 3: Configure SendGrid

1. Navigate to Dashboard > System Settings > Mail Configuration
2. Set Mail Driver to SMTP (or Mailgun if using API)
3. Enter the following settings:
   • Mail Host: smtp.sendgrid.net
   • Mail Port: 587
   • Encryption: Select TLS
   • Username: apikey (literally the word "apikey")
   • Password: Your SendGrid API key
   • From Address: Your verified sender email
   • From Name: Your website or organization name
4. Click Save Configuration
5. Test the configuration

Task 4: Test Email Configuration

1. Scroll to the Test Email Configuration section
2. Enter a valid email address in the Email Address field
3. Click Send Test Email
4. Wait for the system to process (button will show "Sending...")
5. Check the result message:
   • Green success message: Email sent successfully - check the recipient inbox
   • Red error message: Configuration issue - review the error details
6. If successful, check the recipient's inbox (and spam folder) for the test email
7. If failed, review error message and adjust configuration accordingly

Task 5: Switch Mail Provider

1. Navigate to Dashboard > System Settings > Mail Configuration
2. Select a different Mail Driver from the dropdown:
   • SMTP: Standard SMTP server
   • Sendmail: Server's sendmail program
   • Mailgun: Mailgun API
   • SES: Amazon Simple Email Service
   • Postmark: Postmark API
3. Update all relevant fields for the new provider
4. Click Save Configuration
5. Send a test email to verify the new configuration works

Task 6: Update Mail Credentials

1. Navigate to Dashboard > System Settings > Mail Configuration
2. Locate the Username and Password fields
3. Enter the new credentials
4. Leave other settings unchanged if they're still correct
5. Click Save Configuration
6. Test email delivery to confirm the new credentials work

Settings and Options

Mail Driver

• Type: Select dropdown
• Required: Yes
• Description: The mail delivery method to use
• Options:
  • SMTP: Standard SMTP server (most common)
  • Sendmail: Uses server's sendmail program
  • Mailgun: Mailgun email service API
  • SES: Amazon Simple Email Service
  • Postmark: Postmark email service
• Default: SMTP

Mail Host

• Type: Text
• Required: Yes
• Description: The hostname or IP address of your SMTP server
• Example: smtp.gmail.com, smtp.office365.com, mail.yourdomain.com
• Note: Must be accessible from your web server

Mail Port

• Type: Number
• Required: Yes
• Description: The port number for SMTP connection
• Common Values:
  • 587: TLS encryption (recommended)
  • 465: SSL encryption
  • 25: No encryption (not recommended)
• Default: 587

Encryption

• Type: Select dropdown
• Required: No
• Description: The encryption method for secure email transmission
• Options:
  • None: No encryption (not recommended for production)
  • TLS: Transport Layer Security (recommended)
  • SSL: Secure Sockets Layer
• Default: TLS
• Recommendation: Always use TLS or SSL for security

Username

• Type: Text
• Required: No (depends on mail server)
• Description: SMTP authentication username, typically your email address
• Example: yourname@example.com, apikey (for SendGrid)
• Note: Some servers don't require authentication

Password

• Type: Password
• Required: No (depends on mail server)
• Description: SMTP authentication password or API key
• Security: Stored securely in encrypted format
• Note: For Gmail, use an App Password, not your regular password

From Address

• Type: Email
• Required: Yes
• Description: The email address that appears as the sender
• Example: noreply@yourdomain.com, support@yourdomain.com
• Note: Must be a valid email address; some providers require verification

From Name

• Type: Text
• Required: Yes
• Description: The name that appears as the sender
• Example: "My Website", "Customer Support", "Your Company Name"
• Note: This appears in the recipient's inbox as the sender name

Permissions

Access to Mail Configuration is controlled by the following permission:

• system.settings: Required to view and modify mail configuration settings

Tips and Best Practices

• Use App Passwords: For Gmail and similar services, always use app-specific passwords rather than your main account password
• Verify Sender Addresses: Many email providers require you to verify sender addresses before allowing emails from them
• Test After Changes: Always send a test email after modifying configuration to ensure it works
• Check Spam Folders: Test emails may land in spam folders initially; check there if you don't see them in the inbox
• Use TLS Encryption: Always use TLS or SSL encryption for security and to prevent emails being marked as spam
• Monitor Sending Limits: Be aware of your email provider's sending limits (e.g., Gmail has daily limits)
• Keep Credentials Secure: Never share SMTP credentials or commit them to version control
• Use Dedicated Email Services: For high-volume sending, use dedicated services like SendGrid or Mailgun
• Configure SPF/DKIM: Set up SPF and DKIM records for your domain to improve email deliverability
• Monitor Bounce Rates: Keep track of bounced emails and maintain a clean email list

Troubleshooting

Problem: Test Email Not Received

Solution:

• Check the recipient's spam/junk folder
• Verify the recipient email address is correct
• Check that the SMTP configuration is saved correctly
• Review server logs for error messages
• Ensure your server can connect to the SMTP host (check firewall rules)
• Verify the SMTP port is not blocked by your hosting provider

Problem: Authentication Failed Error

Solution:

• Double-check username and password are correct
• For Gmail, ensure you're using an App Password, not your regular password
• Verify the email account is active and not locked
• Check if two-factor authentication is enabled (may require app passwords)
• Ensure the username format is correct (some servers need full email, others just the local part)
• Try resetting the email account password

Problem: Connection Timeout

Solution:

• Verify the mail host address is correct
• Check that the port number is correct (587 for TLS, 465 for SSL)
• Ensure your server's firewall allows outbound connections on the SMTP port
• Contact your hosting provider to verify SMTP ports aren't blocked
• Try using a different port (some hosts block port 25)
• Check if your server's IP is blacklisted

Problem: SSL/TLS Certificate Error

Solution:

• Verify the encryption setting matches your mail server's requirements
• Try switching between TLS and SSL
• Ensure your server's SSL certificates are up to date
• Check that your PHP installation has OpenSSL enabled
• Contact your mail provider to verify their SSL/TLS requirements

Problem: Emails Marked as Spam

Solution:

• Configure SPF records for your domain
• Set up DKIM signing for your emails
• Use a verified sender address
• Ensure your server's IP isn't blacklisted (check at mxtoolbox.com)
• Use a reputable email service provider
• Include proper unsubscribe links in emails
• Avoid spam trigger words in subject lines and content

Problem: "From Address Not Verified" Error

Solution:

• Log into your email provider's dashboard
• Find the sender verification section
• Add and verify the from address you want to use
• Wait for verification email and click the confirmation link
• Update the mail configuration with the verified address

Problem: Daily Sending Limit Exceeded

Solution:

• Check your email provider's sending limits
• For Gmail: 500 emails per day for free accounts, 2000 for Google Workspace
• Consider upgrading to a dedicated email service for higher volumes
• Implement email queuing to spread sends over time
• Use a professional email service like SendGrid or Mailgun for bulk sending

Problem: Configuration Saves But Doesn't Work

Solution:

• Clear application cache after saving configuration
• Restart any queue workers if using queued emails
• Check that environment variables aren't overriding database settings
• Verify file permissions on configuration files
• Check server logs for PHP errors during email sending

Related Modules

• General Settings: Main system configuration including site information
• Contact Messages: Relies on mail configuration for sending responses
• Notifications: Uses mail configuration for email notifications
• Users: Password reset emails use mail configuration