Skip to main content

SMTP configuration

Configure email for user invitations, password resets, and notifications.

Is SMTP required?​

No. SMTP is optional for self-hosted deployments.

Without SMTP:

  • Email verification is disabled
  • Users register via invitation tokens
  • Password reset requires admin intervention

Environment variables​

VariableDescriptionRequired
SMTP_HOSTSMTP server hostnameYes
SMTP_PORTSMTP server portYes
SMTP_SECUREUse TLS (true/false)No
SMTP_USERSMTP usernameIf auth required
SMTP_PASSWORDSMTP passwordIf auth required
SMTP_FROM_EMAILSender email addressYes
SMTP_FROM_NAMESender display nameNo

Example configurations​

Gmail (App Password)​

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=your@gmail.com
SMTP_FROM_NAME=Synjar
note

Use an App Password, not your regular Gmail password. Enable 2FA and create an App Password in Google Account settings.

SendGrid​

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=apikey
SMTP_PASSWORD=SG.your_sendgrid_api_key
SMTP_FROM_EMAIL=noreply@yourcompany.com
SMTP_FROM_NAME=Synjar

Mailgun​

SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=postmaster@mg.yourcompany.com
SMTP_PASSWORD=your-mailgun-password
SMTP_FROM_EMAIL=noreply@yourcompany.com
SMTP_FROM_NAME=Synjar

Amazon SES​

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-ses-smtp-user
SMTP_PASSWORD=your-ses-smtp-password
SMTP_FROM_EMAIL=noreply@yourverifieddomain.com
SMTP_FROM_NAME=Synjar

Self-hosted (Mailcow, etc.)​

SMTP_HOST=mail.yourcompany.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=synjar@yourcompany.com
SMTP_PASSWORD=your-password
SMTP_FROM_EMAIL=synjar@yourcompany.com
SMTP_FROM_NAME=Synjar

Development with Mailpit​

For local development, use Mailpit (included in docker-compose):

SMTP_HOST=localhost
SMTP_PORT=6202
SMTP_SECURE=false
SMTP_FROM_EMAIL=noreply@synjar.local
SMTP_FROM_NAME=Synjar Dev

View emails at http://localhost:6203

Testing SMTP​

After configuration, test by:

  1. Creating a new user
  2. Checking if invitation email is sent
  3. Verifying email content and links

Troubleshooting​

Connection refused​

  • Verify hostname and port
  • Check firewall rules
  • Ensure SMTP server is accessible

Authentication failed​

  • Verify username and password
  • For Gmail, use App Password
  • Check if account has 2FA requirements

Emails not delivered​

  • Check spam folder
  • Verify FROM address is allowed
  • Check SPF/DKIM records for your domain

Timeout errors​

  • Increase connection timeout
  • Try different port (25, 465, 587)
  • Check if ISP blocks SMTP

See also​