Email setup

For a quick overview, refer to the user guide provided here: Password Reset

General setup

LibreChat supports multiple email providers:

• Mailgun API - Recommended for servers that block SMTP ports
• SMTP Services - Traditional email sending via Gmail, Outlook, or custom mail servers

Common Configuration

These variables are used by both Mailgun and SMTP:

Mailgun Configuration (Recommended)

Mailgun is particularly useful for deployments on servers that block SMTP ports to prevent spam. When both MAILGUN_API_KEY and MAILGUN_DOMAIN are set, LibreChat will use Mailgun instead of SMTP.

SMTP Configuration

Basic Configuration

If you want to use one of the predefined services, configure only these variables: For more info about supported email services: https://community.nodemailer.com/2-0-0-beta/setup-smtp/well-known-services/

Advanced Configuration

If you want to use a generic SMTP service or need advanced configuration for one of the predefined providers, configure these variables as well:

Setup with Mailgun

To set up Mailgun, follow these steps:

1. Sign up for a Mailgun account at mailgun.com
2. Add and verify your domain in the Mailgun dashboard
3. Navigate to the API Keys section and copy your Private API key
4. In the .env file, modify the variables as follows:

Setup with Gmail

To set up Gmail, follow these steps:

1. Create a Google Account and enable 2-step verification.
2. In the Google Account settings, click on the "Security" tab and open "2-step verification."
3. Scroll down and open "App passwords." Choose "Mail" for the app and select "Other" for the device, then give it a random name.
4. Click on "Generate" to create a password, and copy the generated password.
5. In the .env file, modify the variables as follows:

Setup with custom mail server

To set up a custom mail server, follow these steps:

1. Gather your SMTP login data from your provider. The steps are different for each, but they will usually list values for all variables.
2. In the .env file, modify the variables as follows, assuming some sensible example values:

Complete Configuration Examples

Example 1: Mailgun Configuration

# ===================================
# Email Configuration - Mailgun
# ===================================
# Mailgun is recommended for servers that block SMTP ports
 
# Required Mailgun settings
MAILGUN_API_KEY=your-mailgun-api-key
MAILGUN_DOMAIN=mg.yourdomain.com
 
# Optional: For EU region
# MAILGUN_HOST=https://api.eu.mailgun.net
 
# Common email settings
EMAIL_FROM=[email protected]
EMAIL_FROM_NAME=LibreChat
 
# Enable password reset functionality
ALLOW_PASSWORD_RESET=true

Example 2: Gmail SMTP Configuration

# ===================================
# Email Configuration - Gmail SMTP
# ===================================
# Traditional SMTP configuration
 
# Gmail service configuration
EMAIL_SERVICE=gmail
EMAIL_USERNAME=[email protected]
EMAIL_PASSWORD=your-app-password
 
# Common email settings
EMAIL_FROM=[email protected]
EMAIL_FROM_NAME=LibreChat
 
# Enable password reset functionality
ALLOW_PASSWORD_RESET=true

Example 3: Custom SMTP Server Configuration

# ===================================
# Email Configuration - Custom SMTP
# ===================================
# For custom mail servers
 
# SMTP server details
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_ENCRYPTION=starttls
EMAIL_USERNAME=[email protected]
EMAIL_PASSWORD=your-password
 
# Optional settings
# EMAIL_ENCRYPTION_HOSTNAME=
# EMAIL_ALLOW_SELFSIGNED=false
 
# Common email settings
EMAIL_FROM=[email protected]
EMAIL_FROM_NAME=LibreChat
 
# Enable password reset functionality
ALLOW_PASSWORD_RESET=true

Troubleshooting

Mailgun Issues

1. Authentication Failed: Ensure your Mailgun API key is correct and has sending permissions
2. Domain Not Found: Verify your Mailgun domain is correctly configured in your Mailgun account
3. EU Region Issues: If your Mailgun account is in the EU region, make sure to set MAILGUN_HOST=https://api.eu.mailgun.net
4. Fallback to SMTP: If only one of MAILGUN_API_KEY or MAILGUN_DOMAIN is set, the system will fall back to SMTP configuration

SMTP Issues

1. Connection Refused: Check if your server allows outbound SMTP connections on the specified port
2. Authentication Failed: Verify your username and password are correct
3. Gmail App Password: For Gmail, you must use an app-specific password, not your regular password
4. Self-signed Certificates: If your mail server uses self-signed certificates, set EMAIL_ALLOW_SELFSIGNED=true

General Issues

1. No Emails Sent: Check the LibreChat logs for error messages
2. Unsecured Password Reset: This occurs when neither Mailgun nor SMTP is properly configured
3. From Address Issues: Ensure the EMAIL_FROM address is valid and authorized to send from your mail service