Email Settings

Configure SMTP settings for sending system emails, notifications, and renewal reminders.

Breadcrumb: System Configuration > Email Settings

Overview

Email Settings control how PteroCA sends transactional emails including:

• Account registration and verification

• Password reset requests

• Server notifications

• Payment confirmations

• System alerts

• Server renewal notifications

All email delivery is handled through SMTP (Simple Mail Transfer Protocol). You must configure a valid SMTP server to enable email functionality.

Two Types of Settings:

1. SMTP Configuration - Server connection settings for email delivery

2. Renewal Notifications - Automated reminders for server renewals

Settings Overview

SMTP Configuration (5 settings):

Setting	Type	CLI	Admin Panel	Description
SMTP Server	Text	✓	✓	Address of SMTP server
SMTP Port	Number	✓	✓	Port for SMTP connection
SMTP Username	Text	✓	✓	Authentication username
SMTP Password	Secret	✓	✓	Authentication password
SMTP From	Email	✓	✓	Sender email address

Renewal Notifications (3 settings):

Setting	Type	CLI	Admin Panel	Description
Enable Renewal Notifications	Boolean		✓	Automatically send renewal reminders
Notification Minimum Frequency	Number		✓	Minimum hours between notifications
On-Demand Minimum Hours	Number		✓	Minimum hours before on-demand notification

Configuration via CLI Wizard

The CLI configuration wizard covers all 5 SMTP settings during initial setup. Renewal notification settings are only configurable via Admin Panel.

Run the Wizard

cd /var/www/pteroca
php bin/console pteroca:system:configure

Email Configuration Prompts

--- Email settings ---

SMTP Server [smtp.mailtrap.io]:
smtp.gmail.com

SMTP Port [587]:
587

SMTP Username [username]:
[email protected]

SMTP Password:
*****

SMTP From (E-mail) [[email protected]]:
[email protected]

Testing SMTP During Setup

The wizard validates SMTP credentials during configuration by attempting a test connection.

Configuration via Admin Panel

All email settings can be managed through the Admin Panel with the added benefit of a built-in SMTP connection test.

Access Email Settings

1. Log in to the Admin Panel

2. Navigate to Settings in the main menu

3. Click Email

4. Update values

5. Click Test SMTP Connection (recommended)

6. Click Save

Setting Details

SMTP Server

Setting Code: smtp_server Field Type: Text Required: Yes Default: smtp.mailtrap.io

The hostname or IP address of your SMTP server.

Common SMTP Servers:

Provider	SMTP Server	Notes
Gmail	smtp.gmail.com	Requires App Password
Outlook/Office 365	smtp.office365.com	-
Yahoo	smtp.mail.yahoo.com	-
SendGrid	smtp.sendgrid.net	API key required
Mailgun	smtp.mailgun.org	-
Amazon SES	email-smtp.region.amazonaws.com	Replace region
Mailtrap (Testing)	smtp.mailtrap.io	Development only
Postmark	smtp.postmarkapp.com	Server token required

Format:

smtp.provider.com

Validation:

• Must be valid hostname or IP

• No protocol prefix (no http:// or https://)

• No trailing slash

SMTP Port

Setting Code: smtp_port Field Type: Number Required: Yes Default: 587

The port number used for SMTP connection.

Common Ports:

Port	Protocol	Security	When to Use
587	SMTP	TLS/STARTTLS	Recommended - Modern standard
465	SMTPS	SSL	Legacy SSL connections
25	SMTP	None	Not recommended - Often blocked
2525	SMTP	TLS	Alternative to 587 (some providers)

Recommendations:

• Use port 587 with TLS - Most compatible and secure

• Avoid port 25 - Often blocked by ISPs and cloud providers

• Port 465 for legacy systems - Older SSL-only clients

• Port 2525 as fallback - If 587 is blocked

Firewall Considerations: Ensure outbound connections on your chosen port are allowed:

# Test SMTP connection
telnet smtp.gmail.com 587

SMTP Username

Setting Code: smtp_username Field Type: Text Required: Yes (for most providers) Default: None

Username for SMTP authentication.

Common Formats:

Full Email Address:

[email protected]

Username Only:

panel

API Key (SendGrid, etc.):

apikey

Provider-Specific Examples:

Provider	Username Format	Example
Gmail	Full email	[email protected]
Outlook	Full email	[email protected]
SendGrid	apikey	apikey
Mailgun	SMTP username from dashboard	[email protected]
Amazon SES	IAM access key ID	AKIAIOSFODNN7EXAMPLE
Mailtrap	Username from inbox settings	Generated by Mailtrap

Gmail App Passwords: If using Gmail, you must generate an App Password:

1. Enable 2-Step Verification on your Google account

2. Go to https://myaccount.google.com/apppasswords

3. Select "Mail" and your device

4. Generate password

5. Use generated 16-character password as SMTP password

SMTP Password

Setting Code: smtp_password Field Type: Secret (Password) Required: Yes (for most providers) Default: None

Password or API key for SMTP authentication.

Security:

• Stored encrypted in database

• Displayed as ***** in admin panel

• Never exposed in logs

Provider-Specific:

Gmail:

• Use App Password (not regular password)

• 16-character format: xxxx xxxx xxxx xxxx

SendGrid:

• Use API key as password

• Format: SG.***

Amazon SES:

• Use SMTP password (not IAM secret key)

• Generate in SES console under SMTP Settings

Mailgun:

• Use SMTP password from domain settings

• Not the same as API key

Best Practices:

• Never share SMTP password

• Use dedicated SMTP credentials (not personal account)

• Rotate passwords periodically

• Use provider-specific API keys when available

SMTP From (Sender Address)

Setting Code: smtp_from Field Type: Email Required: Yes Default: [email protected]

The email address shown as the sender in outgoing emails.

Format:

[email protected]

Best Practices:

1. Match Your Domain:

   • Use same domain as site URL

   • Improves email deliverability

   • Reduces spam filtering

2. Use Descriptive Address:

   • noreply@ - Don't monitor replies

   • support@ - If you monitor and respond

   • notifications@ - Automated messages

3. Avoid Personal Addresses:

   • Don't use personal Gmail/Outlook

   • Use professional domain

Deliverability Considerations:

SPF Record: Add SPF record to DNS to authorize sending server:

v=spf1 include:_spf.provider.com ~all

DKIM: Configure DKIM signatures with your provider for authentication.

DMARC: Set DMARC policy to prevent spoofing:

v=DMARC1; p=none; rua=mailto:[email protected]

Examples:

Good:

[email protected]
[email protected]
[email protected]

Bad:

[email protected]          (personal address)
noreply@localhost           (invalid domain)
admin                       (not an email)

Renewal Notification Settings

The following settings control automated server renewal reminders sent to customers.

Note: These settings are only available via Admin Panel, not the CLI wizard.

Access Renewal Notification Settings

1. Log in to the Admin Panel

2. Navigate to Settings in the main menu

3. Click Email

4. Scroll to Renewal Notifications section

5. Configure settings

6. Click Save

Setting Details

Enable Renewal Notifications

Setting Code: renewal_notification_enabled Field Type: Boolean (Toggle) Required: No Default: false

Enable automatic email reminders for customers when their servers are approaching expiration.

When Enabled:

• System automatically sends renewal reminders

• Notifications sent based on configured frequency

• Helps reduce server suspensions due to non-payment

• Improves customer retention

When Disabled:

• No automatic renewal reminders sent

• Customers must manually track renewal dates

• Higher risk of unexpected suspensions

• Manual notification only

How It Works:

1. Automatic Checking:

   • System checks server expiration dates via cron job

   • Runs periodically (based on cron schedule)

   • Identifies servers expiring soon

2. Notification Triggers:

   • Server expiring within configured timeframe

   • Minimum frequency elapsed since last notification

   • Customer has valid email address

3. Email Content:

   • Server name and expiration date

   • Renewal cost and payment link

   • Account balance information

   • Instructions for renewal

Benefits:

1. For Customers:

   • Timely reminders prevent service interruption

   • Convenient payment links

   • Clear renewal information

2. For Administrators:

   • Reduced support tickets

   • Fewer suspended servers

   • Better cash flow

   • Improved customer satisfaction

Best Practices:

• Enable for production environments

• Set reasonable frequency (24-48 hours)

• Test email delivery first

• Monitor notification logs

• Combine with grace period before suspension

Use Cases:

Small Hosting Business:

Enable: Yes
Frequency: 48 hours
On-Demand: 24 hours
Result: Customers get reminders every 2 days, starting 7 days before expiration

Large-Scale Provider:

Enable: Yes
Frequency: 24 hours
On-Demand: 12 hours
Result: Frequent reminders, customers can request additional reminders

Development Environment:

Enable: No
Result: No notifications sent during testing

Notification Minimum Frequency (Hours)

Setting Code: renewal_notification_min_period_hours Field Type: Number Required: Only if notifications enabled Default: 48 Min: 1 hour Recommended: 24-72 hours

Minimum number of hours that must elapse between automatic renewal notification emails to the same customer.

Purpose: Prevents spam by limiting notification frequency. Even if server expires soon, system won't send another notification until this time has passed since the last one.

How It Works:

Last notification: Dec 10, 2024 10:00 AM
Frequency setting: 48 hours
Next allowed: Dec 12, 2024 10:00 AM

If cron runs on Dec 11, 2024 2:00 PM:
- Time elapsed: 28 hours
- 48 hours not reached
- No notification sent

If cron runs on Dec 12, 2024 3:00 PM:
- Time elapsed: 53 hours
- 48 hours reached
- Notification sent (if server still needs renewal)

Recommended Values:

Frequency	Use Case	Pros	Cons
12 hours	Urgent renewals	Quick reminders	May annoy customers
24 hours	Standard	Balanced	Multiple daily emails possible
48 hours	Recommended	Not overwhelming	Fewer reminders
72 hours	Conservative	Minimal emails	May miss urgency
168 hours (7 days)	Minimal	One reminder per week	Not urgent enough

Considerations:

1. Customer Experience:

   • Too frequent = spam complaints

   • Too infrequent = missed renewals

   • 48 hours is good balance

2. Expiration Timeline:

   • If server expires in 3 days

   • With 48-hour frequency

   • Customer gets 1-2 reminders

3. Cron Schedule:

   • If cron runs daily

   • 24-hour frequency = 1 email/day max

   • 48-hour frequency = 1 email every 2 days max

Examples:

Aggressive (Not Recommended):

Minimum Frequency: 6 hours
Result: Customers could receive up to 4 emails per day
Risk: Spam complaints, email filtering

Balanced (Recommended):

Minimum Frequency: 48 hours
Result: Maximum one email every 2 days
Benefit: Regular reminders without overwhelming

Conservative:

Minimum Frequency: 96 hours (4 days)
Result: Maximum one email every 4 days
Use: When renewal window is long (30+ days)

Best Practices:

• Start with 48 hours

• Monitor customer feedback

• Adjust based on renewal patterns

• Consider timezone differences

• Document in Terms of Service

On-Demand Minimum Hours Before Notification

Setting Code: renewal_notification_on_demand_min_hours Field Type: Number Required: Only if notifications enabled Default: 24 Min: 1 hour Recommended: 12-48 hours

Minimum number of hours that must pass since the last notification before a customer can manually request an on-demand renewal reminder.

Purpose: Prevents abuse of manual notification feature while allowing customers to request reminders when needed.

How It Works:

Scenario 1 - Request Allowed:

Last notification: Dec 10, 2024 10:00 AM
On-demand setting: 24 hours
Current time: Dec 11, 2024 2:00 PM

Time elapsed: 28 hours
28 hours > 24 hours
✓ Customer can request notification

Scenario 2 - Request Denied:

Last notification: Dec 10, 2024 10:00 AM
On-demand setting: 24 hours
Current time: Dec 10, 2024 8:00 PM

Time elapsed: 10 hours
10 hours < 24 hours
✗ Request denied - too soon

On-Demand vs Automatic:

Type	Trigger	Frequency Limit
Automatic	Cron job	Notification Minimum Frequency
On-Demand	Customer request	On-Demand Minimum Hours

Common Configurations:

Strict:

On-Demand Minimum: 48 hours
Use: Prevent frequent manual requests

Balanced (Recommended):

On-Demand Minimum: 24 hours
Use: Allow daily manual reminders

Flexible:

On-Demand Minimum: 12 hours
Use: Allow twice-daily manual reminders

Very Flexible:

On-Demand Minimum: 1 hour
Use: Testing or special circumstances
Risk: Potential abuse

Relationship to Automatic Frequency:

Typically, on-demand minimum should be shorter than automatic frequency:

Automatic Frequency: 48 hours (less frequent)
On-Demand Minimum: 24 hours (more frequent)

Reasoning:
- Automatic goes to all customers
- On-demand is customer-initiated
- Customers won't abuse their own inbox

Use Cases:

Customer forgot to renew:

• Automatic: Sent 2 days ago

• On-demand: 24-hour minimum

• Customer can request reminder now

• Includes payment link

Customer wants to check balance:

• Last notification: Yesterday

• On-demand: 24 hours

• Can request new notification

• Shows current balance and cost

Emergency notification:

• Server expiring in hours

• Customer requests reminder

• If minimum met, sends immediately

• Helps prevent last-minute suspensions

Best Practices:

1. Set Lower Than Automatic:

   • Automatic: 48 hours

   • On-Demand: 24 hours

   • Gives customers more control

2. Consider Abuse Prevention:

   • Don't set too low (< 6 hours)

   • Monitor request patterns

   • Adjust based on usage

3. Customer Communication:

   • Explain feature in documentation

   • Show countdown in UI

   • Clear error messages when denied

4. Testing:

   • Test on-demand feature

   • Verify timing enforcement

   • Check email delivery

Error Handling:

When customer requests on-demand notification too soon:

Error Message:
"A renewal notification was sent 8 hours ago.
You can request another notification in 16 hours."

Or with timestamp:
"Next notification available: Dec 11, 2024 at 10:00 AM"

Recommended Settings:

Enable Renewal Notifications: Yes
Notification Minimum Frequency: 48 hours
On-Demand Minimum Hours: 24 hours

Explanation:
- Automatic reminders every 2 days
- Customers can request daily if needed
- Balanced between automation and control

Testing SMTP Configuration

Admin Panel Test

The Email Settings page includes a built-in connection test:

1. Configure all SMTP settings

2. Click Test SMTP Connection button

3. Check for success/error message

4. If successful, click Save

Test Verification:

• Verifies connection to SMTP server

• Authenticates with provided credentials

• Confirms sender address is valid

• Does NOT send actual test email

Send Test Email

To send an actual test email:

# Coming soon - test email command
php bin/console pteroca:email:test [email protected]

Alternatively, trigger a password reset to test full email flow.

Common SMTP Providers Setup

Gmail

Settings:

SMTP Server: smtp.gmail.com
SMTP Port: 587
SMTP Username: [email protected]
SMTP Password: [App Password]
SMTP From: [email protected]

Requirements:

• Enable 2-Step Verification

• Generate App Password

• Less secure app access: Not needed with App Password

Limitations:

• 500 emails/day limit (free account)

• 2000 emails/day (Google Workspace)

SendGrid

Settings:

SMTP Server: smtp.sendgrid.net
SMTP Port: 587
SMTP Username: apikey
SMTP Password: [Your SendGrid API Key]
SMTP From: [email protected]

Setup:

1. Create SendGrid account

2. Verify sender domain

3. Generate API key with "Mail Send" permission

4. Use apikey as username

5. Use API key as password

Advantages:

• 100 emails/day (free tier)

• Excellent deliverability

• Detailed analytics

Mailgun

Settings:

SMTP Server: smtp.mailgun.org
SMTP Port: 587
SMTP Username: [email protected]
SMTP Password: [SMTP Password from Mailgun]
SMTP From: [email protected]

Setup:

1. Create Mailgun account

2. Add and verify domain

3. Copy SMTP credentials from domain settings

4. Configure DNS records (SPF, DKIM)

Note: SMTP password is different from API key.

Amazon SES

Settings:

SMTP Server: email-smtp.us-east-1.amazonaws.com
SMTP Port: 587
SMTP Username: [SMTP Username from SES]
SMTP Password: [SMTP Password from SES]
SMTP From: [email protected]

Setup:

1. Verify email address or domain in SES console

2. Create SMTP credentials in SES settings

3. Move out of sandbox mode for production

4. Configure DNS records

Advantages:

• 62,000 emails/month (free tier with EC2)

• Pay-as-you-go pricing

• High deliverability

Mailtrap (Development Only)

Settings:

SMTP Server: smtp.mailtrap.io
SMTP Port: 587 (or 2525, 25, 465)
SMTP Username: [From Mailtrap Inbox]
SMTP Password: [From Mailtrap Inbox]
SMTP From: [email protected]

Purpose:

• Testing email functionality

• Do not use in production

• Captures emails without sending

Setup:

1. Create free Mailtrap account

2. Copy SMTP credentials from inbox

3. Configure in PteroCA

4. All emails appear in Mailtrap inbox

Best Practices

Security

1. Use TLS/SSL:

   • Always use port 587 with TLS

   • Never send credentials unencrypted

2. Strong Passwords:

   • Use provider-generated API keys

   • Rotate credentials periodically

3. Dedicated Credentials:

   • Use separate SMTP account for panel

   • Not your personal email credentials

Deliverability

1. SPF/DKIM/DMARC:

   • Configure DNS authentication records

   • Prevents spoofing and improves delivery

2. Matching Domain:

   • Send from same domain as panel

   • Builds sender reputation

3. Monitor Blacklists:

   • Check if sending IP is blacklisted

   • Use dedicated IP for high volume

4. Warm-Up Period:

   • Start with low volume

   • Gradually increase over weeks

Monitoring

1. Track Bounces:

   • Monitor bounce rates

   • Clean up invalid addresses

2. Watch for Blocks:

   • Check provider limits

   • Monitor SMTP errors in logs

3. Test Regularly:

   • Send test emails periodically

   • Verify across different providers

Troubleshooting

Connection Failures

Problem: Cannot connect to SMTP server

Possible Causes:

• Incorrect SMTP server address

• Port blocked by firewall

• Server/provider down

Solutions:

1. Test Connection:

   telnet smtp.gmail.com 587

2. Check Firewall:

   # Allow outbound SMTP
   sudo ufw allow out 587/tcp

3. Verify Provider Status:

   • Check provider status page

   • Try alternative port (2525)

4. Check DNS:

   nslookup smtp.gmail.com

Authentication Failures

Problem: SMTP authentication failed

Causes:

• Incorrect username/password

• App password not generated (Gmail)

• Less secure apps blocked

Solutions:

1. Verify Credentials:

   • Double-check username and password

   • Ensure no extra spaces

2. Gmail:

   • Generate App Password

   • Enable 2-Step Verification first

3. SendGrid:

   • Verify API key has "Mail Send" permission

   • Username must be exactly apikey

4. Test Credentials: Use test connection in Admin Panel

Emails Not Sending

Problem: SMTP connection successful but emails don't arrive

Possible Causes:

• Spam filtering

• Invalid sender address

• Domain not verified

• Recipient blocks

Solutions:

1. Check Spam Folder:

   • First place to look

   • Mark as "Not Spam"

2. Verify Sender Domain:

   • Ensure sender domain is verified with provider

   • Check SPF/DKIM/DMARC records

3. Review Email Logs:

   # Check panel logs
   tail -f var/log/prod.log | grep email

4. Test Different Recipient:

   • Try different email provider

   • Rule out recipient-side blocking

Emails Marked as Spam

Problem: Emails consistently go to spam

Causes:

• Missing SPF/DKIM records

• Sender reputation

• Spam-like content

Solutions:

1. Configure DNS Records:

   • Add SPF record

   • Enable DKIM

   • Set DMARC policy

2. Improve Content:

   • Avoid spam trigger words

   • Include plain text version

   • Add unsubscribe link

3. Build Reputation:

   • Start with low volume

   • Maintain low bounce rate

   • Avoid sending to invalid addresses

4. Use Dedicated IP:

   • Consider dedicated IP (high volume)

   • Warm up new IPs gradually

Gmail App Password Issues

Problem: Cannot generate App Password

Cause: 2-Step Verification not enabled

Solution:

1. Go to https://myaccount.google.com/security

2. Enable 2-Step Verification

3. Generate App Password at https://myaccount.google.com/apppasswords

4. Use 16-character password (without spaces)

SendGrid API Key Errors

Problem: SendGrid authentication fails

Common Mistakes:

• Using API key as username (should be apikey)

• Using wrong type of API key

• Insufficient permissions

Solution:

1. Username must be: apikey (lowercase, exactly)

2. Password must be: Full API key starting with SG.

3. API key must have "Mail Send" permission

4. Verify sender domain in SendGrid dashboard

Related Settings

• General Settings - Configure sender domain in Site URL

• Security Settings - Email verification requirements

Additional Resources

• SMTP Protocol - Technical background

• SPF Record Generator - Create SPF records

• DMARC Guide - Email authentication

• Gmail SMTP Guide - Google Workspace SMTP