📧 docs: Mailgun API Email Configuration (#317)

* 📧 docs: Mailgun API email configuration

* 📝 docs: Update agents configuration note to include custom endpoint option

Author: danny-avila

pages/docs/configuration/authentication/email.mdx

@@ -1,6 +1,6 @@
 ---
 title: Email setup
-description: This guide explains how to configure the secure email verification/password reset. You can configure it to work with various email services, including Gmail and custom mail servers.
+description: This guide explains how to configure the secure email verification/password reset. You can configure it to work with various email services, including Gmail, Mailgun, and custom mail servers.
 ---
 
 # Email verification and Password Reset
@@ -9,6 +9,35 @@ For a quick overview, refer to the user guide provided here: [Password Reset](/d
 
 ## 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:
@@ -19,8 +48,6 @@ For more info about supported email services: https://community.nodemailer.com/2
     ['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='],
-    ['EMAIL_FROM_NAME', 'string', 'From name.','EMAIL_FROM_NAME='],
-    ['EMAIL_FROM', 'string', 'From email address. Required.','EMAIL_FROM=noreply@librechat.ai'],
   ]}
 />
 
@@ -39,7 +66,30 @@ If you want to use a generic SMTP service or need advanced configuration for one
 />
 
 <Callout type="warning" title="Warning">
-**Failing to perform either of the below setups 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!**
+**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
@@ -80,3 +130,98 @@ To set up a custom mail server, follow these steps:
     ['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

pages/docs/configuration/dotenv.mdx

@@ -1104,13 +1104,32 @@ For more information: **[LDAP/AD Authentication](/docs/configuration/authenticat
 
 ### Password Reset
 
-Email is used for account verification and password reset. See: **[Email setup](/docs/configuration/authentication/email)**
+Email is used for account verification and password reset. LibreChat supports both Mailgun API and traditional SMTP services. See: **[Email setup](/docs/configuration/authentication/email)**
 
-**Important Note**: All of the service or host, username, and password, and the From address must be set for email to work.
+**Important Note**: You must configure either Mailgun (recommended for servers that block SMTP) or SMTP for email to work.
+
+> **Warning**: Failing to set valid values for either Mailgun or SMTP will result in LibreChat using the unsecured password reset!
+
+#### Mailgun Configuration (Recommended)
+
+Mailgun is particularly useful for deployments on servers that block SMTP ports. 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 (required for Mailgun).','MAILGUN_DOMAIN=mg.yourdomain.com'],
+    ['MAILGUN_HOST', 'string', 'Custom Mailgun API host (optional). Use https://api.eu.mailgun.net for EU region.','MAILGUN_HOST=https://api.mailgun.net'],
+    ['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='],
+  ]}
+/>
+
+#### SMTP Configuration
+
+If Mailgun is not configured, LibreChat will fall back to SMTP settings.
 
 > **Warning**: If using `EMAIL_SERVICE`, **do NOT** set the extended connection parameters:
 > HOST, PORT, ENCRYPTION, ENCRYPTION_HOSTNAME, ALLOW_SELFSIGNED.
-> Failing to set valid values here will result in LibreChat using the unsecured password reset!
 
 See: **[nodemailer well-known-services](https://community.nodemailer.com/2-0-0-beta/setup-smtp/well-known-services/)**
 

pages/docs/configuration/librechat_yaml/object_structure/agents.mdx

@@ -74,7 +74,7 @@ disableBuilder: false
 
 **Default:** `[]` (empty list, all providers allowed)
 
-**Note:** Must be one of the following:
+**Note:** Must be one of the following, or a custom endpoint name as defined in your [configuration](/docs/configuration/librechat_yaml/object_structure/custom_endpoint#name):
     - `openAI, azureOpenAI, google, anthropic, assistants, azureAssistants, bedrock`
 
 **Example:**

pages/docs/features/password_reset.mdx

@@ -23,17 +23,21 @@ description: This feature enables email-based password reset functionality for y
 
 ## Overview
 
-This feature enables email-based password reset functionality for your LibreChat server. You can configure it to work with various email services, including Gmail and custom mail servers.
+This feature enables email-based password reset functionality for your LibreChat server. You can configure it to work with various email services, including Mailgun API, Gmail, and custom mail servers.
 
 ## Key Features
 
-- Supports multiple email services, including Gmail and custom mail servers
+- Supports multiple email services:
+  - **Mailgun API** - Recommended for servers that block SMTP ports
+  - **Gmail** and other predefined SMTP services
+  - **Custom mail servers** with advanced SMTP configuration
 - Allows for basic and advanced configuration options
-- Enables email-based password reset functionality for your LibreChat server
+- Enables secure email-based password reset functionality for your LibreChat server
 
 ## Setup Options
 
-- Basic Configuration: Use predefined services with minimal configuration
-- Advanced Configuration: Configure generic SMTP services or customize settings for predefined providers
+- **Mailgun Configuration**: Use Mailgun's API for reliable email delivery, especially useful when SMTP ports are blocked
+- **Basic SMTP Configuration**: Use predefined services like Gmail with minimal configuration
+- **Advanced SMTP Configuration**: Configure generic SMTP services or customize settings for any mail provider
 
-**For further details, refer to the configuration guides provided here: [Password Reset](/docs/configuration/authentication/email)**
+**For detailed setup instructions, refer to the configuration guide: [Email Setup](/docs/configuration/authentication/email)**