Skip to main content
Chatwoot requires email configuration for sending notifications, password resets, and other transactional emails. This guide covers all email-related configuration options.

​
Email Sender Configuration

​
MAILER_SENDER_EMAIL
string
required
The email address from which all outgoing emails are sent.Formats:Example: Chatwoot <[email protected]>

​
SMTP Configuration

SMTP is the most common method for sending emails. Configure these variables to use your SMTP server.
​
SMTP_DOMAIN
string
SMTP domain for HELO checking.Example: chatwoot.com
​
SMTP_ADDRESS
string
SMTP server address.Special values:
  • Leave empty to use sendmail (postfix)
  • Set to mailhog when using docker-compose for development
  • Set to localhost or your SMTP server address in other environments
Examples:
  • smtp.gmail.com
  • smtp.sendgrid.net
  • smtp.mailgun.org
​
SMTP_PORT
number
SMTP server port.Common ports:
  • 587 - TLS/STARTTLS (recommended)
  • 465 - SSL
  • 25 - Unencrypted (not recommended)
  • 1025 - Mailhog (development)
Default: 1025
​
SMTP_USERNAME
string
SMTP authentication username.Note: Usually your email address or API username.
​
SMTP_PASSWORD
string
SMTP authentication password or API key.
​
SMTP_AUTHENTICATION
string
SMTP authentication method.Options:
  • plain
  • login
  • cram_md5
Note: Leave empty if authentication is not required.
​
SMTP_ENABLE_STARTTLS_AUTO
boolean
Automatically enable STARTTLS if available.Default: trueRecommendation: Keep enabled for secure connections.
​
SMTP_OPENSSL_VERIFY_MODE
string
OpenSSL verification mode for SMTP connections.Options:
  • none - No verification (not recommended for production)
  • peer - Verify the server certificate (recommended)
  • client_once - Verify once during initial connection
  • fail_if_no_peer_cert - Fail if no peer certificate
Default: peerSee ActionMailer SSL Documentation
​
SMTP_TLS
boolean
Force TLS connection.Note: Only set if required by your SMTP server.
​
SMTP_SSL
boolean
Use SSL connection.Note: Only set if required by your SMTP server.
​
SMTP_OPEN_TIMEOUT
number
Timeout in seconds for opening SMTP connection.Example: 5
​
SMTP_READ_TIMEOUT
number
Timeout in seconds for reading SMTP responses.Example: 10

​
Incoming Email Configuration

Configure these settings to handle incoming emails for conversation continuity.
​
MAILER_INBOUND_EMAIL_DOMAIN
string
Domain for reply email addresses when conversation continuity is enabled.Example: replies.chatwoot.com
​
RAILS_INBOUND_EMAIL_SERVICE
string
Email ingress service for handling incoming emails.Options:
  • relay - For Exim, Postfix, Qmail
  • mailgun - For Mailgun
  • mandrill - For Mandrill
  • postmark - For Postmark
  • sendgrid - For SendGrid
  • ses - For Amazon SES
See ActionMailbox Basics
​
RAILS_INBOUND_EMAIL_PASSWORD
string
Password for inbound email webhook authentication.Security: Set this to a strong password of your choice and use it in the inbound webhook URL.

​
Service-Specific Configuration

​
Mailgun

​
MAILGUN_INGRESS_SIGNING_KEY
string
Mailgun webhook signing key for verifying incoming requests.

​
Mandrill

​
MANDRILL_INGRESS_API_KEY
string
Mandrill API key for incoming email authentication.

​
Amazon SES

​
ACTION_MAILBOX_SES_SNS_TOPIC
string
SNS topic ARN for ActionMailbox with Amazon SES.Format: arn:aws:sns:region:account-id:topic-nameNote: Only required when RAILS_INBOUND_EMAIL_SERVICE=ses

​
Inbound Webhook Setup

For Postmark and SendGrid, configure your inbound webhook with the following URL format: 
https://actionmailbox:[YOUR_RAILS_INBOUND_EMAIL_PASSWORD]@[YOUR_CHATWOOT_DOMAIN]/rails/action_mailbox/[RAILS_INBOUND_EMAIL_SERVICE]/inbound_emails
Example: 
https://actionmailbox:[email protected]/rails/action_mailbox/postmark/inbound_emails
For Postmark: Ensure the “Include raw email content in JSON payload” checkbox is selected in the inbound webhook section.

​
Provider-Specific Examples

​
Gmail / Google Workspace

SMTP_ADDRESS=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-app-specific-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_DOMAIN=gmail.com
MAILER_SENDER_EMAIL=Your Name <[email protected]m>
For Gmail, you need to create an App Password instead of using your regular password.

​
SendGrid

SMTP_ADDRESS=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=your-sendgrid-api-key
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_DOMAIN=yourdomain.com
MAILER_SENDER_EMAIL=Your App <[email protected]m>

​
Mailgun

SMTP_ADDRESS=smtp.mailgun.org
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-mailgun-smtp-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_DOMAIN=yourdomain.com
MAILER_SENDER_EMAIL=Your App <[email protected]m>

​
Amazon SES

SMTP_ADDRESS=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=your-ses-smtp-username
SMTP_PASSWORD=your-ses-smtp-password
SMTP_AUTHENTICATION=login
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_DOMAIN=yourdomain.com
MAILER_SENDER_EMAIL=Your App <[email protected]m>
Make sure your sender email is verified in Amazon SES.

​
Postfix (Local Sendmail)

To use local sendmail with Postfix: 
# Leave SMTP_ADDRESS empty
SMTP_ADDRESS=
MAILER_SENDER_EMAIL=Your App <[email protected]m>
When SMTP_ADDRESS is empty, Chatwoot automatically uses sendmail for email delivery.

​
Testing Email Configuration

After configuring your email settings, test the configuration:
  1. Start your Chatwoot instance
  2. Attempt to sign up or reset a password
  3. Check your inbox for the email
  4. Check Chatwoot logs for any email delivery errors

​
Troubleshooting

Emails not being delivered:
  • Verify SMTP credentials are correct
  • Check if your SMTP provider requires additional authentication
  • Verify your sender email is authorized by your SMTP provider
  • Check Chatwoot logs for detailed error messages
  • Ensure your firewall allows outbound connections on the SMTP port
SSL/TLS connection errors:
  • Try setting SMTP_OPENSSL_VERIFY_MODE=none (temporarily for debugging)
  • Verify the correct port (587 for TLS, 465 for SSL)
  • Check if SMTP_ENABLE_STARTTLS_AUTO should be enabled or disabled
Authentication failures:
  • Verify the authentication method matches your provider’s requirements
  • For Gmail, ensure you’re using an App Password
  • Check if your provider requires API keys instead of passwords

Build docs developers (and LLMs) love

Get started for freeTalk to us