Email Configuration

Configure SMTP, Mailgun, Postmark, and other mail providers for Pterodactyl Panel

Pterodactyl Panel uses email for user notifications, password resets, and administrative alerts. Configure your preferred mail provider in the .env file.

Supported Mail Drivers

The Panel supports multiple mail drivers:

• SMTP - Standard SMTP server (recommended for most users)
• Mailgun - Mailgun API
• Postmark - Postmark API
• SES - Amazon Simple Email Service
• Sendmail - Local sendmail binary
• Log - Write emails to log files (development only)

Basic Configuration

Mail Driver Selection

.env

MAIL_MAILER=smtp

MAIL_MAILER · string · default: "smtp"

Mail driver to use. Options: smtp, mailgun, postmark, ses, sendmail, log

From Address

.env

MAIL_FROM_ADDRESS=[e-mail]
MAIL_FROM_NAME="Pterodactyl Panel"

MAIL_FROM_ADDRESS · string · required

Email address that appears as the sender.

Use a valid email address from your domain to prevent emails from being marked as spam.

MAIL_FROM_NAME · string · default: "Pterodactyl Panel"

Name that appears as the sender in email clients.

SMTP Configuration

Gmail

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=[e-mail]
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=[e-mail]
MAIL_FROM_NAME="Pterodactyl Panel"

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=username
MAIL_PASSWORD=password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=[e-mail]
MAIL_FROM_NAME="Pterodactyl Panel"

MAIL_MAILER=smtp
MAIL_HOST=smtp.office365.com
MAIL_PORT=587
MAIL_USERNAME=[e-mail]
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=[e-mail]
MAIL_FROM_NAME="Pterodactyl Panel"

SMTP Parameters

MAIL_HOST · string · required

SMTP server hostname.

MAIL_PORT · integer · default: "25"

SMTP server port. Common values:

• 25 - Standard SMTP (often blocked)
• 587 - SMTP with STARTTLS (recommended)
• 465 - SMTP over SSL

MAIL_USERNAME · string

SMTP authentication username.

MAIL_PASSWORD · string

SMTP authentication password.

MAIL_ENCRYPTION · string · default: "tls"

Encryption method. Options: tls, ssl, or leave empty for none.

EHLO Domain

.env

MAIL_EHLO_DOMAIN=panel.example.com

MAIL_EHLO_DOMAIN · string

Domain used in the SMTP EHLO/HELO command. Set this to your panel’s domain to prevent mail servers like Gmail from rejecting your emails.

If not set, defaults to the server’s hostname which may be ‘localhost’.

Mailgun Configuration

.env

MAIL_MAILER=mailgun
MAILGUN_DOMAIN=mg.example.com
MAILGUN_SECRET=key-your-api-key
MAILGUN_ENDPOINT=api.mailgun.net
MAIL_FROM_ADDRESS=[e-mail]
MAIL_FROM_NAME="Pterodactyl Panel"

MAIL_MAILER=mailgun
MAILGUN_DOMAIN=mg.example.com
MAILGUN_SECRET=key-your-api-key
MAILGUN_ENDPOINT=api.eu.mailgun.net
MAIL_FROM_ADDRESS=[e-mail]
MAIL_FROM_NAME="Pterodactyl Panel"

You’ll need to install the Mailgun PHP SDK:

composer require mailgun/mailgun-php symfony/http-client nyholm/psr7

Postmark Configuration

.env

MAIL_MAILER=postmark
POSTMARK_TOKEN=your-server-token
MAIL_FROM_ADDRESS=[e-mail]
MAIL_FROM_NAME="Pterodactyl Panel"

You’ll need to install the Postmark PHP SDK:

composer require wildbit/swiftmailer-postmark

Amazon SES Configuration

.env

MAIL_MAILER=ses
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
MAIL_FROM_ADDRESS=[e-mail]
MAIL_FROM_NAME="Pterodactyl Panel"

You’ll need to install the AWS SDK:

composer require aws/aws-sdk-php

Sendmail Configuration

.env

MAIL_MAILER=sendmail
MAIL_SENDMAIL_PATH="/usr/sbin/sendmail -bs -i"
MAIL_FROM_ADDRESS=[e-mail]
MAIL_FROM_NAME="Pterodactyl Panel"

MAIL_SENDMAIL_PATH · string · default: "/usr/sbin/sendmail -bs -i"

Path to the sendmail binary with arguments.

Testing Email Configuration

After configuring email settings, test the connection:

php artisan p:environment:mail

This interactive command will:

1. Prompt you for mail settings
2. Send a test email
3. Verify the configuration works

Manual Test

You can also send a test email using Tinker:

php artisan tinker

Mail::raw('Test email from Pterodactyl Panel', function($message) {
    $message->to('[e-mail]')
            ->subject('Test Email');
});

Troubleshooting

Emails Not Sending

1. Check your mail logs:

   tail -f storage/logs/laravel-*.log
   

2. Verify queue workers are running (if using queues):

   php artisan queue:work --tries=3
   

3. Test SMTP connectivity:

   telnet smtp.example.com 587
   

Common Issues

Connection Refused

• Verify the SMTP host and port are correct
• Check if your firewall allows outbound connections on the SMTP port
• Ensure the SMTP service is running on the remote server

Authentication Failed

• Double-check username and password
• For Gmail, use an App Password instead of your regular password
• Verify two-factor authentication settings

Emails Go to Spam

• Set up SPF, DKIM, and DMARC records for your domain
• Use MAIL_EHLO_DOMAIN matching your panel’s domain
• Ensure MAIL_FROM_ADDRESS uses your domain
• Consider using a dedicated email service (Mailgun, Postmark, SES)

SSL Certificate Verification Failed

• Ensure your server has up-to-date CA certificates
• Update ca-certificates package: apt-get update && apt-get install ca-certificates
• For self-signed certificates, consider using tls instead of ssl

Security Best Practices

Use TLS Encryption

Always use MAIL_ENCRYPTION=tls or ssl in production to encrypt email traffic.

Dedicated Email Service

Consider using dedicated services like Mailgun or Postmark for better deliverability.

Valid From Address

Use a real email address from your domain to improve deliverability and avoid spam filters.

DNS Records

Configure SPF, DKIM, and DMARC records to authenticate your emails.