4 · Email (SMTP)

TL;DR

Objective — wire transactional email and prove it actually sends — the hard part is finding where SMTP resolves at runtime, because the most common vendor family loads it from the DB and the panel’s warning banner lies about it.

User part + done-when

👤 User part — fill the SMTP fields in the admin panel, click the panel’s “Test SMTP” button, and confirm a real password-reset email lands in an inbox; an agent runs the source greps and writes the .env fallback but can’t read your mailbox.

Done when the runtime source of truth is confirmed against source, “Test SMTP” passes, a real reset email arrives end-to-end, and shared/.env carries real MAIL_* fallbacks.  ·  ⏱ 20–45 min  ·  🔀 mixed (👤 panel + inbox, 🤖 greps + .env).

Background

Transactional email is a MUST — password resets, invoices, and notifications all depend on it, and section 1 of page 3 warned you not to change the admin email until mail works. The hard part isn’t the SMTP fields; it’s knowing where the app actually reads them from — and on the most common CodeCanyon vendor family, the admin UI actively lies about that.

SSH artisan uses $PHP_BIN

Any artisan you run over SSH here (config cache, test sends) must use the $PHP_BIN resolved on page 3, never bare php.

Steps

1. Find the real source of truth

Before touching any field, decide where SMTP config actually resolves at runtime. The brand survey (page 2) already flagged whether the vendor ships a CustomConfigProvider; confirm it now.

flowchart TD
    Q{"Does a CustomConfigProvider /<br/>SettingsProvider rewrite mail config<br/>at boot from a DB table?"}
    Q -->|Yes — Froiden family| DB["DB table is truth<br/>(email_settings).<br/>Configure the ADMIN PANEL.<br/>.env MAIL_* = fallback only"]
    Q -->|No admin Email tab at all| ENV["Configure shared/.env MAIL_*<br/>(see Phase 8 email infra)"]
    Q -->|Panel present, no provider| PANEL["Admin panel writes config<br/>directly — use it"]

1. Grep for a provider that rewrites mail config at runtime.

   grep -rn "mail\.mailers\.smtp\|Config::set.*mail" app/Providers/ app/Http/Middleware/ 2>/dev/null | head
   find app/ -name "*ConfigProvider*" -o -name "*SettingsProvider*" 2>/dev/null
   # Expected: a provider that calls Config::set('mail...'), or no match

   • ✅ If a provider calls Config::set('mail.mailers.smtp.*', DB::table(...)), the database overrides .env and the admin panel is the source of truth; otherwise .env is.

Froiden family — the “APP_ENV changed” banner LIES

SocietyPro / ResiDoro / Worksuite / RentalPro and siblings register a CustomConfigProvider (e.g. app/Providers/CustomConfigProvider.php) that unconditionally loads SMTP from the email_settings table on every request (only demo/development skip it). The banner — “you changed APP_ENV=codecanyon… SMTP details below won’t be taken from here” — fires on a naive env('APP_ENV') !== 'codecanyon' check and has nothing to do with actual SMTP resolution. Ignore it: fill the admin panel, save, done. .env MAIL_* is ignored at runtime (fallback only).

The lesson generalizes beyond this one banner:

Treat every vendor UI warning as a hypothesis, not a fact

The cost of trusting the banner was 30+ minutes of debugging .env; the cost of verifying it was one grep + one file read (2 minutes). When a vendor banner implies a code-path change (“do X or Y breaks”), grep for the real decision point before acting.

2. Configure SMTP in the admin panel

Admin → Config → SMTP (or Settings → Email). This is a panel form a person fills and a panel button a person clicks — the test send and the inbox check are human-verified.

Who does this

👤 User fills the SMTP fields, clicks the panel’s “Test SMTP” button, and confirms the password-reset email arrives in a real inbox — a browser action plus a mailbox check only a person completes.

1. Fill the SMTP fields from your Phase 4 SMTP credentials + brand profile.

   Field	Value
   Mail From Name	App name (brand profile)
   Mail From Email	admin@[DOMAIN]
   SMTP Host	e.g. smtp.hostinger.com
   SMTP Port	587 (TLS) or 465 (SSL)
   Username / Password	mailbox creds — paste the password via the clipboard bridge from page 3 §1
   Encryption	TLS (587) / SSL (465)

   • ✅ All fields are filled from real credentials; the password was pasted via the clipboard bridge.

2. Save, then click the panel’s own “Test SMTP” button — not artisan tinker. Tinker sends through Laravel’s default mailer, which a CLI context may not have reconfigured via the provider yet.

   • ✅ “Test SMTP” succeeds and the dashboard “SMTP details are not correct” banner disappears — that’s your real success signal.

3. Trigger a password-reset on a test account and confirm the email arrives.

   • ✅ A real password-reset email lands end-to-end in the inbox.

No admin Email tab at all?

Configure shared/.env directly (MAIL_MAILER, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_ENCRYPTION, MAIL_FROM_ADDRESS, MAIL_FROM_NAME). Provider selection (SendGrid, Mailgun, SES, Brevo, Resend, Titan) belongs to Phase 8 email infrastructure.

3. Set a sensible .env fallback (defence in depth)

Even when the DB path is truth, leave real MAIL_* values in shared/.env. If the email_settings row is corrupted or the provider query fails, Laravel falls back to .env. Real values = mail still works; garbage values = mail breaks silently.

1. Append the fallback idempotently (Python-free here, but grep -q guards against duplicates; special-char passwords stay out of this block).

   grep -q "^MAIL_HOST=" shared/.env || cat >> shared/.env <<'EOF'
   # SMTP fallback (.env defaults; runtime config overridden by CustomConfigProvider from DB)
   MAIL_MAILER=smtp
   MAIL_HOST=smtp.hostinger.com
   MAIL_PORT=465
   MAIL_ENCRYPTION=ssl
   MAIL_FROM_ADDRESS=admin@[DOMAIN]
   MAIL_FROM_NAME="[APP_NAME]"
   EOF
   # Expected: the MAIL_* block is appended once (no duplicate on re-run)

   • ✅ shared/.env carries real MAIL_* fallback values, appended only once.

4. Review email templates & hygiene

1. Review the email templates (if the vendor exposes Admin → Email Templates) — welcome, password-reset, invoice, and notification — setting the sender name, logo, and footer to match your brand (the email header logo you uploaded on page 3 lives here on some vendors).

   • ✅ Sender name, logo, and footer match the brand on every reviewed template.

2. Confirm no SMTP credentials are committed to git — they belong in shared/.env on the server and your password manager only.

   • ✅ No SMTP secrets are tracked in git.

Checklist

Do not mark this step done until every box below is checked.

• 🤖 Source confirmed — where SMTP resolves at runtime (DB-via-provider vs .env) is confirmed; the Froiden banner was verified against source, not trusted.
• 👤 Panel SMTP saved — “Test SMTP” passes and the dashboard error banner is gone.
• 👤 Reset email received — a real password-reset email arrived end-to-end.
• 🤖 .env fallback set — shared/.env carries real MAIL_* fallback values; no SMTP secrets in git.
• 👤 Templates reviewed — sender, logo, footer reviewed if the vendor exposes them.

→Next step

5 · Payments & plans