Invitations, portal magic links, password reset, and branded notifications leave the server only when SMTP is configured and a queue worker or cron drain is running. The Web Installer leaves MAIL_MAILER=log. That is correct until you complete this page — it is not production mail.
This is not workspace Settings. Workspace-only users do not configure SMTP. Never paste production SMTP passwords into public tickets or this documentation.
Platform Admin → Settings → Mail / SMTP (/admin/settings/mail). Values here overlay MAIL_* in .env. Fill the UI; do not duplicate the password in .env unless you have no platform host saved yet.
Fields
Section titled “Fields”| Label | What to enter |
|---|---|
| Email provider | Optional preset (Gmail, Microsoft 365, Mailgun, SendGrid, …) that fills host/port/encryption. Custom SMTP if your host is not listed |
| Mailer | SMTP for real delivery, or Log (development) to write files only |
| Host | SMTP hostname from the provider |
| Port | 587 (STARTTLS, recommended), 465 (SSL / Implicit TLS), 2525 (alternate), or Custom |
| Encryption | STARTTLS (TLS), SSL / Implicit TLS, or None. Must match the port |
| Username | SMTP login (SendGrid: the literal text apikey) |
| Password | Stored encrypted. Leave blank to keep an existing password |
| From address / From name | Must be a domain the provider is allowed to send as |
- Sign in as a platform administrator. Use the account created at install.
- Open Mail / SMTP and switch Mailer to SMTP. Fill host, port, encryption, username, password, From. Save until the page says platform mail settings are active.
- Confirm a worker or drain is running. cPanel: cron drain every minute. VPS: persistent
queue:work. If you skip this, the next step cannot succeed. - Click Send test email. The test goes to the signed-in administrator’s address. Expected: inbox receives “Platform mail test.”
| Port | Typical use |
|---|---|
587 |
Submission with STARTTLS — most shared-host docs start here |
465 |
Implicit TLS — do not mix with a “TLS on 587” profile |
2525 |
Alternate STARTTLS when the host blocks 587 |
Port 25 is often blocked on cloud VPS networks.
The log driver writes the message into backend/storage/logs/laravel.log. It does not send email. Search the log for the recipient address: if the full MIME is there, SMTP is not in use yet.
If it fails
Section titled “If it fails”- UI says sent, inbox empty → Queue not running; look at Platform Admin → Queues (
/admin/queues, title Failed jobs). - Wrong
APP_URL, TLS mismatch, type disabled under Communications so the action succeeds with no email. - Workspace members looking in Settings → they will not find SMTP. See Settings.
Related: Queue · Troubleshooting mail.