Skip to main content
XyraPanel sends transactional emails for password resets, email verification, welcome messages, and server notifications. Email configuration is managed through the admin panel’s settings interface, not environment variables.
Email configuration is stored in the database and can be updated at runtime through the admin panel at /admin/settings/email.

​
Email Drivers

XyraPanel supports multiple email delivery methods: Send emails via SMTP server. Compatible with most email providers. Use cases:
  • Gmail, Office 365, or custom mail servers
  • Self-hosted mail servers
  • General-purpose SMTP providers

​
Sendmail

Use the system’s sendmail binary. Use cases:
  • Systems with sendmail/postfix already configured
  • Simple local mail delivery
Sendmail requires proper server configuration and is less reliable than SMTP for most use cases.

​
Mailgun

Dedicated Mailgun driver (API-based). Use cases:
  • High-volume transactional email
  • Advanced deliverability features

​
SMTP Configuration

When using SMTP driver, configure these settings in the admin panel:
​
driver
string
default:"smtp"
Email driver to use: smtp, sendmail, or mailgun.
​
service
string
Pre-configured SMTP service provider. Supported values:
  • gmail - Gmail
  • outlook - Outlook/Office 365
  • yahoo - Yahoo Mail
  • icloud - iCloud Mail
  • mailgun - Mailgun
  • sendgrid - SendGrid
  • mailjet - Mailjet
  • mailtrap - Mailtrap (testing)
  • zoho - Zoho Mail
  • Custom - Leave blank and configure host/port manually
When using a pre-configured service, you only need to provide username and password. Host and port are set automatically.
​
host
string
required
SMTP server hostname (e.g., smtp.gmail.com).Required only when service is not set.
​
port
number
default:"587"
SMTP server port:
  • 587 - TLS/STARTTLS (recommended)
  • 465 - SSL
  • 25 - Unencrypted (not recommended)
​
encryption
string
default:"tls"
Encryption method:
  • tls - STARTTLS (port 587)
  • ssl - SSL/TLS (port 465)
  • none - No encryption (not recommended)
​
username
string
required
SMTP authentication username (usually your email address).
​
password
string
required
SMTP authentication password or app-specific password.
Use app-specific passwords for Gmail and other providers that support them. Never use your main account password!
​
fromAddress
string
required
Email address used in the “From” field (e.g., [email protected]).
​
fromName
string
default:"XyraPanel"
Display name used in the “From” field.

​
Provider-Specific Setup

​
Gmail Setup

  1. Enable 2-factor authentication on your Google account
  2. Generate an app-specific password at myaccount.google.com/apppasswords
  3. Configure in admin panel:
Driver: smtp
Service: gmail
Username: [email protected]
Password: your-app-specific-password
From Address: [email protected]
From Name: YourPanel Name
Gmail limits sending to 500 emails per day for free accounts.

​
Office 365 / Outlook Setup

  1. Use your Office 365 email and password
  2. If using 2FA, create an app password
  3. Configure in admin panel:
Driver: smtp
Service: outlook
Username: [email protected]
Password: your-password-or-app-password
From Address: [email protected]
From Name: YourPanel Name

​
Custom SMTP Server

For custom mail servers, leave service blank and configure manually:
Driver: smtp
Service: (leave blank)
Host: mail.example.com
Port: 587
Encryption: tls
Username: [email protected]
Password: your-smtp-password
From Address: [email protected]
From Name: YourPanel Name

​
SendGrid Setup

  1. Create a SendGrid account and API key at sendgrid.com
  2. Configure in admin panel:
Driver: smtp
Service: sendgrid
Username: apikey
Password: your-sendgrid-api-key
From Address: [email protected]
From Name: YourPanel Name
SendGrid requires domain verification for production use.

​
Mailgun Setup

Option 1: Use SMTP driver
Driver: smtp
Service: mailgun
Username: [email protected]
Password: your-mailgun-smtp-password
From Address: [email protected]
From Name: YourPanel Name
Option 2: Use Mailgun driver (API-based)
Driver: mailgun
# Additional Mailgun-specific configuration

​
Mailtrap for Testing

Mailtrap catches all emails for testing without sending to real recipients.
  1. Create account at mailtrap.io
  2. Get SMTP credentials from your inbox
  3. Configure in admin panel:
Driver: smtp
Service: mailtrap
Username: your-mailtrap-username
Password: your-mailtrap-password
From Address: [email protected]
From Name: XyraPanel Test
Only use Mailtrap in development! Emails won’t be delivered in production.

​
Email Templates

XyraPanel sends emails for these events:
TemplatePurposeTrigger
Welcome EmailWelcome new usersUser account created
Email VerificationVerify email addressesNew user registration
Password ResetReset forgotten passwordUser requests password reset
Server CreatedNotify of new serverServer provisioned for user
Server SuspendedNotify of suspensionServer suspended by admin
Server ReinstalledNotify of reinstallationServer reinstalled
Backup CompletedNotify of backup successBackup creation completed
Admin User CreatedProvide login detailsAdmin creates user account
Email templates can be customized through the admin panel at /admin/settings/email/templates.

​
Testing Email Configuration

After configuring email settings:
1

Save configuration

Update email settings in the admin panel at /admin/settings/email.
2

Send test email

Use the “Send Test Email” button in the admin panel to verify configuration.
3

Check delivery

Verify the test email arrives in your inbox and isn’t marked as spam.
4

Test password reset

Try the “Forgot Password” flow on the login page to test real-world usage.

​
Troubleshooting

Symptoms: “Authentication failed” or “Invalid credentials” errorsSolutions:
  • Verify username and password are correct
  • Use app-specific passwords for Gmail, Office 365, etc.
  • Check if your email provider requires 2FA
  • Ensure “less secure app access” is enabled (if applicable)
Symptoms: “Connection timeout” or “Cannot connect to SMTP server”Solutions:
  • Verify SMTP host and port are correct
  • Check firewall allows outbound connections on the SMTP port
  • Try different ports (587, 465, 25)
  • Verify your server’s IP isn’t blocked by the email provider
Symptoms: Emails arrive in spam folderSolutions:
  • Set up SPF, DKIM, and DMARC records for your domain
  • Use a verified sending domain
  • Ensure “From Address” matches your authenticated domain
  • Use a reputable email service provider
  • Avoid sending too many emails too quickly
Symptoms: No errors but emails don’t arriveSolutions:
  • Check XyraPanel logs for email sending errors
  • Verify email configuration is saved correctly
  • Test with Mailtrap to isolate delivery vs configuration issues
  • Check email provider’s sending limits
  • Verify recipient email address is valid
Symptoms: “SSL/TLS handshake failed” or certificate errorsSolutions:
  • Try switching between tls (port 587) and ssl (port 465)
  • Verify your server has up-to-date CA certificates
  • Check if your SMTP provider has valid SSL certificates
  • Try connecting with openssl s_client -connect smtp.host.com:587 -starttls smtp

​
Email Service Recommendations

​
For Production

SendGrid

Reliable, high-volume email delivery with excellent deliverability.Pros: Free tier (100 emails/day), good deliverability, easy setup

Mailgun

Developer-friendly email API with powerful features.Pros: Free tier (1,000 emails/month), advanced features, reliable

Amazon SES

Cost-effective email service from AWS.Pros: Very cheap, scales infinitely, AWS integration

Postmark

Premium transactional email service.Pros: Excellent deliverability, great support, developer-friendly

​
For Testing

  • Mailtrap - Catches emails in development without sending
  • MailHog - Self-hosted email testing tool
  • Gmail - Quick setup for small deployments

​
Environment vs Database

Email settings are stored in the database, not environment variables. The .env file does not contain email configuration.
This design allows:
  • Runtime configuration changes without restarts
  • Multiple administrators to manage email settings
  • Secure storage of credentials in the database
  • Easy backup and migration of settings

​
Security Best Practices

Never use your primary email password. Always generate app-specific passwords for Gmail, Office 365, and other providers that support them.
Always use encryption (tls or ssl) for SMTP connections. Never send credentials over unencrypted connections.
Email credentials are stored encrypted in the database. Ensure your database has proper access controls.
Create dedicated accounts (like [email protected]) instead of using personal email accounts.
Be aware of your email provider’s rate limits and implement appropriate throttling if needed.

​
Next Steps

Environment Variables

View all configuration options

Security Settings

Configure security features

Build docs developers (and LLMs) love

Get started for freeTalk to us