Skip to main content

​
SMTP Configuration

listmonk uses SMTP to send email campaigns. You can configure multiple SMTP servers and use them individually or as a round-robin pool.
SMTP settings are configured through the Settings UI under Settings → SMTP. The configuration is stored in the database.

​
Multiple SMTP Servers

listmonk supports configuring multiple SMTP servers:
  • Unnamed servers - Combined into a round-robin pool called “email”
  • Named servers - Available as individual messenger options in campaigns
If you configure multiple named SMTP servers, campaigns can select which specific server to use.

​
SMTP Settings

​
enabled
boolean
default:"true"
Enable or disable this SMTP server.
​
host
string
required
SMTP server hostname or IP address.Examples: smtp.gmail.com, smtp.sendgrid.net, localhost
​
port
integer
required
SMTP server port.Common ports:
  • 25 - Standard SMTP (often blocked by cloud providers)
  • 587 - SMTP with STARTTLS (recommended)
  • 465 - SMTP with TLS/SSL
  • 2525 - Alternative submission port
Some server hosts block outgoing SMTP ports (25, 465). Contact your hosting provider to unblock them before attempting to send emails.
​
auth_protocol
string
default:"plain"
SMTP authentication protocol.Options:
  • plain - PLAIN authentication (most common)
  • login - LOGIN authentication
  • cram - CRAM-MD5 authentication
  • none - No authentication
​
username
string
SMTP username for authentication.
​
password
string
SMTP password for authentication.
​
tls_type
string
default:"STARTTLS"
TLS/SSL connection type.Options:
  • STARTTLS - Upgrade connection to TLS (recommended for port 587)
  • TLS - Direct TLS connection (for port 465)
  • none - No encryption (not recommended for production)
​
tls_skip_verify
boolean
default:"false"
Skip TLS certificate verification.
Only enable this for testing with self-signed certificates. Never use in production.
​
hello_hostname
string
default:""
Hostname to use in the SMTP HELO/EHLO command. Leave empty to use the default.
​
max_conns
integer
default:"10"
Maximum number of concurrent SMTP connections in the pool.
​
idle_timeout
duration
default:"15s"
Maximum idle time for an SMTP connection before closing.
​
wait_timeout
duration
default:"5s"
Maximum time to wait for a connection from the pool.
​
max_msg_retries
integer
default:"2"
Number of times to retry sending a failed message using different connections from the SMTP pool.
These are silent retries at the moment of sending. Messages that fail after all retries are logged as errors.
​
email_headers
array
default:"[]"
Custom email headers to add to all messages sent through this SMTP server.Example: [["X-Custom-Header", "value"]]
​
name
string
default:""
Optional unique name for this SMTP server. When set, the server appears as a separate messenger option in campaigns.

​
Provider-Specific Configurations

​
AWS SES

{
  "enabled": true,
  "host": "email-smtp.us-east-1.amazonaws.com",
  "port": 587,
  "auth_protocol": "plain",
  "username": "YOUR_SMTP_USERNAME",
  "password": "YOUR_SMTP_PASSWORD",
  "tls_type": "STARTTLS",
  "tls_skip_verify": false,
  "max_conns": 10,
  "idle_timeout": "15s",
  "wait_timeout": "5s",
  "max_msg_retries": 2
}
1

Create SMTP Credentials

In AWS SES console, go to SMTP Settings and create SMTP credentials. Note the username and password.
2

Verify Domain or Email

Verify your sending domain or email address in SES.
3

Request Production Access

By default, SES is in sandbox mode. Request production access to send to any email address.
4

Configure Bounce Webhook

See the Bounce Management section to configure SES bounce webhooks.

​
Sendgrid

{
  "enabled": true,
  "host": "smtp.sendgrid.net",
  "port": 587,
  "auth_protocol": "plain",
  "username": "apikey",
  "password": "YOUR_SENDGRID_API_KEY",
  "tls_type": "STARTTLS",
  "tls_skip_verify": false,
  "max_conns": 10,
  "idle_timeout": "15s",
  "wait_timeout": "5s",
  "max_msg_retries": 2
}
For Sendgrid, the username is always apikey and the password is your Sendgrid API key.

​
Postmark

{
  "enabled": true,
  "host": "smtp.postmarkapp.com",
  "port": 587,
  "auth_protocol": "plain",
  "username": "YOUR_SERVER_API_TOKEN",
  "password": "YOUR_SERVER_API_TOKEN",
  "tls_type": "STARTTLS",
  "tls_skip_verify": false,
  "max_conns": 10,
  "idle_timeout": "15s",
  "wait_timeout": "5s",
  "max_msg_retries": 2
}

​
Gmail

{
  "enabled": true,
  "host": "smtp.gmail.com",
  "port": 465,
  "auth_protocol": "login",
  "username": "[email protected]",
  "password": "YOUR_APP_PASSWORD",
  "tls_type": "TLS",
  "tls_skip_verify": false,
  "max_conns": 10,
  "idle_timeout": "15s",
  "wait_timeout": "5s",
  "max_msg_retries": 2
}
Gmail requires an App Password when using 2-factor authentication. Regular passwords won’t work. Also, Gmail has strict sending limits and is not recommended for bulk email campaigns.

​
Mailgun

{
  "enabled": true,
  "host": "smtp.mailgun.org",
  "port": 587,
  "auth_protocol": "plain",
  "username": "[email protected]",
  "password": "YOUR_SMTP_PASSWORD",
  "tls_type": "STARTTLS",
  "tls_skip_verify": false,
  "max_conns": 10,
  "idle_timeout": "15s",
  "wait_timeout": "5s",
  "max_msg_retries": 2
}

​
Custom SMTP Server

{
  "enabled": true,
  "host": "smtp.yourserver.com",
  "port": 587,
  "auth_protocol": "plain",
  "username": "username",
  "password": "password",
  "tls_type": "STARTTLS",
  "tls_skip_verify": false,
  "hello_hostname": "mail.yourdomain.com",
  "max_conns": 10,
  "idle_timeout": "15s",
  "wait_timeout": "5s",
  "max_msg_retries": 2,
  "email_headers": []
}

​
Testing Email Settings

1

Save SMTP Configuration

Configure your SMTP settings in Settings → SMTP and save.
2

Send Test Email

Use the “Send test email” button in the SMTP settings to verify the configuration.
3

Check Logs

If the test fails, check Settings → Logs for detailed error messages.
4

Verify Connectivity

Ensure your server can reach the SMTP host on the specified port. Test with:
telnet smtp.example.com 587

​
Configuration via config.toml

While SMTP is typically configured through the UI, you can also set it in the database settings table. Here’s the structure: 
[
  {
    "enabled": true,
    "host": "smtp.yoursite.com",
    "port": 25,
    "auth_protocol": "cram",
    "username": "username",
    "password": "password",
    "hello_hostname": "",
    "max_conns": 10,
    "idle_timeout": "15s",
    "wait_timeout": "5s",
    "max_msg_retries": 2,
    "tls_type": "STARTTLS",
    "tls_skip_verify": false,
    "email_headers": []
  },
  {
    "enabled": false,
    "name": "Gmail Backup",
    "host": "smtp.gmail.com",
    "port": 465,
    "auth_protocol": "login",
    "username": "[email protected]",
    "password": "password",
    "hello_hostname": "",
    "max_conns": 10,
    "idle_timeout": "15s",
    "wait_timeout": "5s",
    "max_msg_retries": 2,
    "tls_type": "TLS",
    "tls_skip_verify": false,
    "email_headers": []
  }
]

​
Troubleshooting

  • Verify the SMTP host and port are correct
  • Check if your hosting provider blocks outgoing SMTP ports
  • Ensure firewall rules allow outbound connections on the SMTP port
  • Try using an alternative port (e.g., 2525 instead of 587)
  • Double-check username and password
  • For Gmail, ensure you’re using an App Password, not your regular password
  • Verify the auth_protocol matches your provider’s requirements
  • Some providers require specific username formats (e.g., full email address)
  • Verify tls_type matches the port (TLS for 465, STARTTLS for 587)
  • Check if the SMTP server’s SSL certificate is valid
  • Only use tls_skip_verify for testing, never in production
  • Increase max_conns for higher throughput
  • Check your provider’s rate limits
  • Adjust app.concurrency and app.message_rate in performance settings
  • Consider using multiple SMTP servers in round-robin mode

​
Best Practices

Use STARTTLS

Always use STARTTLS or TLS encryption for production email sending.

Monitor Sending Limits

Be aware of your provider’s sending limits and configure concurrency accordingly.

Test Before Campaigns

Always send test emails before launching large campaigns.

Configure Bounces

Set up bounce handling to maintain sender reputation and list hygiene.

Build docs developers (and LLMs) love

Get started for freeTalk to us