SMTP Setup (Email Delivery)

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

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

Login never sends email. SMTP is not used during normal sign-in, unverified-account blocking, password-expired blocking, or login security alerts. Those events are recorded in activity logs and database notifications. SMTP is used only after explicit actions such as resend verification, forgot password, or a configured automation email.

Overview

SMTP Providers

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

If you are testing locally, use the Mailpit preset or set Mailer to log first. Once confirmed, switch back to production 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.

0.1 - Mailpit (Local SMTP)

Mailpit is the local SMTP preset used by the installer and Settings Channels screen. It captures outgoing email locally and exposes a browser inbox.

Mailpit Defaults

Mailer: smtp
Host: 127.0.0.1
Port: 1025
Encryption: none
Username / Password: leave empty
Inbox UI: http://127.0.0.1:8025

The app only fills the preset. It does not install, start, or supervise the Mailpit process. Reference: Mailpit configuration docs.

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 (Placeholders)

Gmail app password placeholder — Gmail App Password creation (replace with your screenshot).

Gmail settings in installer placeholder — Gmail SMTP filled in the installer (replace with your screenshot).

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 (Placeholders)

Mailtrap credentials placeholder — Mailtrap SMTP credentials (replace with your screenshot).

Mailtrap inbox placeholder — Mailtrap inbox showing received test email (replace with your 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 (Placeholders)

Outlook SMTP reference placeholder — Microsoft 365 SMTP reference (replace with your screenshot).

Outlook settings in installer placeholder — Outlook/M365 SMTP filled in the installer (replace with your 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 (Placeholders)

SendGrid API key placeholder — Create a SendGrid API key (replace with your screenshot).

SendGrid sender verification placeholder — Sender verification / domain authentication (replace with your 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.