# Email setup (/docs/configuration/authentication/email)

For a quick overview, refer to the user guide provided here: [Password Reset](/docs/features/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:

<OptionTable
  options={[
    ['EMAIL_FROM', 'string', 'From email address. Required.','EMAIL_FROM=noreply@librechat.ai'],
    ['EMAIL_FROM_NAME', 'string', 'From name (defaults to APP_TITLE if not set).','EMAIL_FROM_NAME=LibreChat'],
  ]}
/>

### 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.

<OptionTable
  options={[
    ['MAILGUN_API_KEY', 'string', 'Your Mailgun API key (required for Mailgun).','MAILGUN_API_KEY='],
    ['MAILGUN_DOMAIN', 'string', 'Your Mailgun domain, e.g., mg.yourdomain.com (required for Mailgun).','MAILGUN_DOMAIN='],
    ['MAILGUN_HOST', 'string', 'Custom Mailgun API host (optional). Use https://api.eu.mailgun.net for EU region.','MAILGUN_HOST=https://api.mailgun.net'],
  ]}
/>

### 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/

<OptionTable
  options={[
    ['EMAIL_SERVICE', 'string', 'Email service (e.g., Gmail, Outlook).','EMAIL_SERVICE='],
    ['EMAIL_USERNAME', 'string', 'Username for authentication.','EMAIL_USERNAME='],
    ['EMAIL_PASSWORD', 'string', 'Password for authentication.','EMAIL_PASSWORD='],
  ]}
/>

**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:

<OptionTable
  options={[
    ['EMAIL_HOST', 'string', 'Mail server host.','EMAIL_HOST='],
    ['EMAIL_PORT', 'number', 'Mail server port.','EMAIL_PORT=25'],
    ['EMAIL_ENCRYPTION', 'string', 'Encryption method (starttls, tls, etc.).','EMAIL_ENCRYPTION='],
    ['EMAIL_ENCRYPTION_HOSTNAME', 'string', 'Hostname for encryption.','EMAIL_ENCRYPTION_HOSTNAME='],
    ['EMAIL_ALLOW_SELFSIGNED', 'boolean', 'Allow self-signed certificates.','EMAIL_ALLOW_SELFSIGNED='],
  ]}
/>

<Callout type="warning" title="Warning">
**Failing to configure either Mailgun or SMTP properly will result in LibreChat using the unsecured password reset! This allows anyone to reset any password on your server immediately, without mail being sent at all!**
</Callout>

## Setup with Mailgun

To set up Mailgun, follow these steps:

1. Sign up for a Mailgun account at [mailgun.com](https://www.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:

<OptionTable
  options={[    
    ['MAILGUN_API_KEY', 'string', 'Your Mailgun private API key', 'MAILGUN_API_KEY=your-mailgun-api-key'],
    ['MAILGUN_DOMAIN', 'string', 'Your verified Mailgun domain', 'MAILGUN_DOMAIN=mg.yourdomain.com'],
    ['EMAIL_FROM', 'string', 'Sender email address', 'EMAIL_FROM=noreply@yourdomain.com'],
    ['EMAIL_FROM_NAME', 'string', 'Sender name', 'EMAIL_FROM_NAME=LibreChat'],
    ['MAILGUN_HOST', 'string', '(Optional) For EU region', 'MAILGUN_HOST=https://api.eu.mailgun.net'],
  ]}
/>

<Callout type="info" title="Note">
If your Mailgun account is in the EU region, make sure to set `MAILGUN_HOST=https://api.eu.mailgun.net`
</Callout>

## 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](https://myaccount.google.com/)**, 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:

<OptionTable
  options={[    
    ['EMAIL_SERVICE', 'string', 'gmail', 'EMAIL_SERVICE=gmail'],
    ['EMAIL_USERNAME', 'string', 'your-email', 'EMAIL_USERNAME=your-email'],
    ['EMAIL_PASSWORD', 'string', 'your-email-password', 'EMAIL_PASSWORD=your-email-password'],
    ['EMAIL_FROM', 'string', 'email address for the from field, e.g., noreply@librechat.ai', 'EMAIL_FROM=noreply@librechat.ai'],
    ['EMAIL_FROM_NAME', 'string', 'My LibreChat Server', 'EMAIL_FROM_NAME=LibreChat'],
  ]}
/>

## 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:

<OptionTable
  options={[    
    ['EMAIL_HOST', 'string', 'Hostname to connect to', 'EMAIL_HOST=mail.example.com'],
    ['EMAIL_PORT', 'integer', 'Port to connect to','EMAIL_PORT=25'],
    ['EMAIL_ENCRYPTION', 'string', 'Encryption type','EMAIL_ENCRYPTION=starttls'],
    ['EMAIL_USERNAME', 'string', 'Your email username','EMAIL_USERNAME=usernale@example.com'],
    ['EMAIL_PASSWORD', 'string', 'Your app password','EMAIL_PASSWORD=password'],
    ['EMAIL_FROM', 'string', 'Email address for the from field','EMAIL_FROM=noreply@librechat.ai'],
    ['EMAIL_FROM_NAME', 'string', 'Name that will appear in the "from" field','EMAIL_FROM_NAME=LibreChat'],
  ]}
/>

## Complete Configuration Examples

### Example 1: Mailgun Configuration

```bash
# ===================================
# 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=noreply@yourdomain.com
EMAIL_FROM_NAME=LibreChat

# Enable password reset functionality
ALLOW_PASSWORD_RESET=true
```

### Example 2: Gmail SMTP Configuration

```bash
# ===================================
# Email Configuration - Gmail SMTP
# ===================================
# Traditional SMTP configuration

# Gmail service configuration
EMAIL_SERVICE=gmail
EMAIL_USERNAME=your-email@gmail.com
EMAIL_PASSWORD=your-app-password

# Common email settings
EMAIL_FROM=your-email@gmail.com
EMAIL_FROM_NAME=LibreChat

# Enable password reset functionality
ALLOW_PASSWORD_RESET=true
```

### Example 3: Custom SMTP Server Configuration

```bash
# ===================================
# Email Configuration - Custom SMTP
# ===================================
# For custom mail servers

# SMTP server details
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_ENCRYPTION=starttls
EMAIL_USERNAME=username@example.com
EMAIL_PASSWORD=your-password

# Optional settings
# EMAIL_ENCRYPTION_HOSTNAME=
# EMAIL_ALLOW_SELFSIGNED=false

# Common email settings
EMAIL_FROM=noreply@example.com
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