SMTP Setup (Email Delivery)

Configure SMTP so the system can send OTP, password reset, admin alerts, and other system emails. This page provides ready-to-use settings for Gmail, Mailtrap, Outlook / Microsoft 365, and SendGrid.

Where to set this? You can configure SMTP during the installer (Step 5: Channels) or later from Configuration. Always use the Test Email option after saving.

Overview

SMTP Providers

0 Common Fields
1 Gmail (SMTP)
2 Mailtrap (Testing)
3 Outlook / Microsoft 365
4 SendGrid (Production)
5 Troubleshooting

If you are testing locally, set Mailer to log first. Once confirmed, switch back to smtp.

0 — Common SMTP Fields

Most providers use the same SMTP fields. Use this table to understand what each value means before applying provider-specific settings.

Field Reference

Mailer: Use smtp for production. Use log for local/dev testing.
Host: SMTP server hostname (example: smtp.gmail.com).
Port: Typically 587 (TLS) or 465 (SSL).
Username: SMTP login (often your email address).
Password: SMTP password (Gmail/M365 may require an App Password).
Encryption: Usually tls. Use ssl only if required by provider.
From Email / From Name: Sender identity shown to users.
Reply-To: Where replies should go (support email recommended).
Timeout: SMTP timeout in seconds (default 30 is fine; raise to 60 on slow hosting).

Using the wrong port/encryption combination is the #1 reason emails fail. If you’re unsure, start with tls + 587.

1 — Gmail (SMTP)

Gmail is a common choice, but it typically requires an App Password (recommended) instead of your normal Gmail password.

Recommended Gmail Settings

Host: smtp.gmail.com
Port: 587
Encryption: tls
Username: your@gmail.com
Password: App Password

Use a Gmail App Password (requires 2-Step Verification enabled).

Gmail Screenshots

Gmail app password reference — Gmail App Password creation (bundled release screenshot).

Gmail settings in installer reference — Gmail SMTP filled in the installer using the bundled release reference.

2 — Mailtrap (Testing)

Mailtrap is best for development/staging. It captures emails in a sandbox inbox so you can test OTP and password reset safely.

Typical Mailtrap Settings

Host: smtp.mailtrap.io (or your Mailtrap SMTP host)
Port: 2525 (commonly) or as shown in Mailtrap
Encryption: tls
Username: Mailtrap username
Password: Mailtrap password

Copy credentials directly from your Mailtrap inbox settings.

Mailtrap Screenshots

Mailtrap credentials reference — Mailtrap SMTP credentials (bundled release screenshot).

Mailtrap inbox reference — Mailtrap inbox showing received test email (bundled release screenshot).

3 — Outlook / Microsoft 365

Microsoft 365 is common in business environments. Some tenants require the admin to enable SMTP Auth for the mailbox.

Recommended Microsoft 365 Settings

Host: smtp.office365.com
Port: 587
Encryption: tls
Username: your@domain.com
Password: Mailbox password / App Password

If sending fails, ask your M365 admin to enable SMTP AUTH for your mailbox.

Outlook Screenshots

Outlook SMTP reference reference — Microsoft 365 SMTP reference (bundled release screenshot).

Outlook settings in installer reference — Outlook/M365 SMTP filled in the installer (bundled release screenshot).

4 — SendGrid (Production SMTP)

SendGrid is a production-grade transactional email provider. It uses SMTP with a special username (apikey) and your generated API key as the password.

Recommended SendGrid Settings

Host: smtp.sendgrid.net
Port: 587
Encryption: tls
Username: apikey
Password: SendGrid API Key

For best deliverability, complete sender verification / domain authentication in SendGrid.

SendGrid Screenshots

SendGrid API key reference — Create a SendGrid API key (bundled release screenshot).

SendGrid sender verification reference — Sender verification / domain authentication (bundled release screenshot).

5 — Troubleshooting

Common Fixes

Test Email fails: confirm Host/Port/Encryption + Username/Password.
Gmail auth error: use an App Password (2FA must be enabled).
M365 auth error: SMTP Auth might be disabled by admin.
Timeout: increase timeout (e.g., 60 seconds) on slow hosting.
Sender rejected: use a valid From Email that your provider allows.

If you suspect SMTP is blocked on hosting, try Mailtrap first to confirm your app is generating emails.

SMTP error example reference — Example SMTP error message (bundled release screenshot).