Docs / SMTP Setup

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 Settings. 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. Gmail or outlook both require enabling of two factor authentication adn then create app password is used for making a smtp app, which is further integrated into the site.

Recommended Gmail Settings

Host: smtp.gmail.com
Port: 587
Encryption: tls
Username: your@gmail.com
Password: App Password, when u save the app the password is shown on the screen

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

Gmail Screenshots

Gmail app password placeholder — Gmail App Password creation

Gmail settings in installer placeholder — Gmail SMTP filled in the settings.

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 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

Outlook SMTP reference placeholder — Microsoft 365 SMTP reference.

Outlook settings in installer placeholder — Outlook/M365 SMTP filled in the app.

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.

4 - 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.