4 · Email (SMTP)

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 4 · Email (SMTP)
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/04-email/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 6
- part_number: 4 (legacy stepNumber frontmatter)
- legacy_step_number: 4
- est_time: 20–45 min
- description: Wire transactional email through the admin panel, and learn the Froiden-family trap where a CustomConfigProvider loads SMTP from the database regardless of APP_ENV — meaning the panel's "APP_ENV changed" warning banner lies and .env MAIL_* values are ignored at runtime.
- tags: codecanyon, laravel, smtp, email

## Execution rules (binding)
- This is Part 4 of phase 6 (20–45 min) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

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

**Steps at a glance:**
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.
2. **Configure SMTP in the admin panel** — `Admin → Config → SMTP` (or `Settings → Email`). The human enters the
   password/secret field; the agent fills non-secret fields, clicks the panel test, and checks logs when browser
   automation is available. Inbox confirmation stays human-owned unless the operator explicitly shares that mailbox session.
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`.
4. **Review email templates & hygiene** — audit the app's email templates and sender hygiene, so customer-facing
   messages are branded, deliverable, and not leaking vendor defaults.

:::note[User part + done-when]
**🔀 User part** — the human supplies SMTP secrets and confirms any real inbox delivery. After the session and secret fields are handled, the agent fills non-secret SMTP fields, clicks the panel's **"Test SMTP"** button, checks logs/banners, runs the source greps, and writes the `.env` fallback.

**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. &nbsp;·&nbsp; **⏱ 20–45 min** &nbsp;·&nbsp; 🔀 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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/) 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.

Before editing mail settings, read `Zaj-PROJECT.md` for the selected environment, mail provider, from-address, vault item pointer, and whether runtime mail config is DB-owned or `.env`-owned. Update those non-secret facts after verification; never store SMTP passwords there.

:::caution[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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/), 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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/02-survey-and-brand/)) already flagged whether the vendor ships a `CustomConfigProvider`; confirm it now.

```mermaid
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"]
```

<Steps>

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

   ```bash
   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.

</Steps>

:::danger[Froiden family — the "APP_ENV changed" banner LIES]
SocietyPro / 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:

:::tip[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 mixed browser flow: human-owned secret fields, agent-owned non-secret fields, save/test clicks, banner checks, and log verification when browser automation is available.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** enters the SMTP password/secret and verifies any real mailbox delivery. 🤖 **Agent** fills the non-secret fields, clicks Save/Test SMTP, reads the resulting banner/logs, and records evidence when browser automation is available.
:::

<Steps>

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 — the human enters the password from the vault; the agent never types or reads it |
   | Encryption | `TLS` (587) / `SSL` (465) |

   - ✅ All fields are filled from real credentials; the password was human-entered from the vault and never exposed to the agent.

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.

</Steps>

:::note[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.

<Steps>

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

   ```bash
   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.

</Steps>

### 4. Review email templates & hygiene

<Steps>

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.

</Steps>

## 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** — human entered secrets; agent saved/tested the panel when browser automation was available; "Test SMTP" passes and the dashboard error banner is gone.
- [ ] **👤 Reset email received** — a real password-reset email arrived end-to-end, or the mailbox-only check is tracked with owner/trigger.
- [ ] **🤖 `.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.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the mail provider, from-address/name, runtime source of truth (admin DB vs `.env`), vault pointer, and last verified date without secrets.

:::next[Next step]
[5 · Payments & plans](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/05-payments-and-plans/)
:::

# 4 · Email (SMTP)

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/04-email/

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

**Steps at a glance:**
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.
2. **Configure SMTP in the admin panel** — `Admin → Config → SMTP` (or `Settings → Email`). The human enters the
   password/secret field; the agent fills non-secret fields, clicks the panel test, and checks logs when browser
   automation is available. Inbox confirmation stays human-owned unless the operator explicitly shares that mailbox session.
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`.
4. **Review email templates & hygiene** — audit the app's email templates and sender hygiene, so customer-facing
   messages are branded, deliverable, and not leaking vendor defaults.

:::note[User part + done-when]
**🔀 User part** — the human supplies SMTP secrets and confirms any real inbox delivery. After the session and secret fields are handled, the agent fills non-secret SMTP fields, clicks the panel's **"Test SMTP"** button, checks logs/banners, runs the source greps, and writes the `.env` fallback.

**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. &nbsp;·&nbsp; **⏱ 20–45 min** &nbsp;·&nbsp; 🔀 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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/) 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.

Before editing mail settings, read `Zaj-PROJECT.md` for the selected environment, mail provider, from-address, vault item pointer, and whether runtime mail config is DB-owned or `.env`-owned. Update those non-secret facts after verification; never store SMTP passwords there.

:::caution[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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/), 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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/02-survey-and-brand/)) already flagged whether the vendor ships a `CustomConfigProvider`; confirm it now.

```mermaid
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"]
```

<Steps>

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

   ```bash
   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.

</Steps>

:::danger[Froiden family — the "APP_ENV changed" banner LIES]
SocietyPro / 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:

:::tip[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 mixed browser flow: human-owned secret fields, agent-owned non-secret fields, save/test clicks, banner checks, and log verification when browser automation is available.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** enters the SMTP password/secret and verifies any real mailbox delivery. 🤖 **Agent** fills the non-secret fields, clicks Save/Test SMTP, reads the resulting banner/logs, and records evidence when browser automation is available.
:::

<Steps>

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 — the human enters the password from the vault; the agent never types or reads it |
   | Encryption | `TLS` (587) / `SSL` (465) |

   - ✅ All fields are filled from real credentials; the password was human-entered from the vault and never exposed to the agent.

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.

</Steps>

:::note[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.

<Steps>

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

   ```bash
   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.

</Steps>

### 4. Review email templates & hygiene

<Steps>

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.

</Steps>

## 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** — human entered secrets; agent saved/tested the panel when browser automation was available; "Test SMTP" passes and the dashboard error banner is gone.
- [ ] **👤 Reset email received** — a real password-reset email arrived end-to-end, or the mailbox-only check is tracked with owner/trigger.
- [ ] **🤖 `.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.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the mail provider, from-address/name, runtime source of truth (admin DB vs `.env`), vault pointer, and last verified date without secrets.

:::next[Next step]
[5 · Payments & plans](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/05-payments-and-plans/)
:::

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.

Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.

EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

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.

Steps at a glance:

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.
Configure SMTP in the admin panel — Admin → Config → SMTP (or Settings → Email). The human enters the password/secret field; the agent fills non-secret fields, clicks the panel test, and checks logs when browser automation is available. Inbox confirmation stays human-owned unless the operator explicitly shares that mailbox session.
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.
Review email templates & hygiene — audit the app’s email templates and sender hygiene, so customer-facing messages are branded, deliverable, and not leaking vendor defaults.

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.

Before editing mail settings, read Zaj-PROJECT.md for the selected environment, mail provider, from-address, vault item pointer, and whether runtime mail config is DB-owned or .env-owned. Update those non-secret facts after verification; never store SMTP passwords there.

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

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.

The lesson generalizes beyond this one banner:

2. Configure SMTP in the admin panel

Admin → Config → SMTP (or Settings → Email). This is a mixed browser flow: human-owned secret fields, agent-owned non-secret fields, save/test clicks, banner checks, and log verification when browser automation is available.

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 — the human enters the password from the vault; the agent never types or reads it
Encryption	`TLS` (587) / `SSL` (465)

✅ All fields are filled from real credentials; the password was human-entered from the vault and never exposed to the agent.

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

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.

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

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.
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 — human entered secrets; agent saved/tested the panel when browser automation was available; “Test SMTP” passes and the dashboard error banner is gone.
👤 Reset email received — a real password-reset email arrived end-to-end, or the mailbox-only check is tracked with owner/trigger.
🤖 .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.
🤖 Project state updated — Zaj-PROJECT.md records the mail provider, from-address/name, runtime source of truth (admin DB vs .env), vault pointer, and last verified date without secrets.

5 · Payments & plans

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 4 · Email (SMTP)
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/04-email/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 6
- part_number: 4 (legacy stepNumber frontmatter)
- legacy_step_number: 4
- est_time: 20–45 min
- description: Wire transactional email through the admin panel, and learn the Froiden-family trap where a CustomConfigProvider loads SMTP from the database regardless of APP_ENV — meaning the panel's "APP_ENV changed" warning banner lies and .env MAIL_* values are ignored at runtime.
- tags: codecanyon, laravel, smtp, email

## Execution rules (binding)
- This is Part 4 of phase 6 (20–45 min) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

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

**Steps at a glance:**
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.
2. **Configure SMTP in the admin panel** — `Admin → Config → SMTP` (or `Settings → Email`). The human enters the
   password/secret field; the agent fills non-secret fields, clicks the panel test, and checks logs when browser
   automation is available. Inbox confirmation stays human-owned unless the operator explicitly shares that mailbox session.
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`.
4. **Review email templates & hygiene** — audit the app's email templates and sender hygiene, so customer-facing
   messages are branded, deliverable, and not leaking vendor defaults.

:::note[User part + done-when]
**🔀 User part** — the human supplies SMTP secrets and confirms any real inbox delivery. After the session and secret fields are handled, the agent fills non-secret SMTP fields, clicks the panel's **"Test SMTP"** button, checks logs/banners, runs the source greps, and writes the `.env` fallback.

**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. &nbsp;·&nbsp; **⏱ 20–45 min** &nbsp;·&nbsp; 🔀 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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/) 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.

Before editing mail settings, read `Zaj-PROJECT.md` for the selected environment, mail provider, from-address, vault item pointer, and whether runtime mail config is DB-owned or `.env`-owned. Update those non-secret facts after verification; never store SMTP passwords there.

:::caution[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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/), 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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/02-survey-and-brand/)) already flagged whether the vendor ships a `CustomConfigProvider`; confirm it now.

```mermaid
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"]
```

<Steps>

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

   ```bash
   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.

</Steps>

:::danger[Froiden family — the "APP_ENV changed" banner LIES]
SocietyPro / 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:

:::tip[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 mixed browser flow: human-owned secret fields, agent-owned non-secret fields, save/test clicks, banner checks, and log verification when browser automation is available.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** enters the SMTP password/secret and verifies any real mailbox delivery. 🤖 **Agent** fills the non-secret fields, clicks Save/Test SMTP, reads the resulting banner/logs, and records evidence when browser automation is available.
:::

<Steps>

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 — the human enters the password from the vault; the agent never types or reads it |
   | Encryption | `TLS` (587) / `SSL` (465) |

   - ✅ All fields are filled from real credentials; the password was human-entered from the vault and never exposed to the agent.

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.

</Steps>

:::note[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.

<Steps>

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

   ```bash
   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.

</Steps>

### 4. Review email templates & hygiene

<Steps>

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.

</Steps>

## 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** — human entered secrets; agent saved/tested the panel when browser automation was available; "Test SMTP" passes and the dashboard error banner is gone.
- [ ] **👤 Reset email received** — a real password-reset email arrived end-to-end, or the mailbox-only check is tracked with owner/trigger.
- [ ] **🤖 `.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.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the mail provider, from-address/name, runtime source of truth (admin DB vs `.env`), vault pointer, and last verified date without secrets.

:::next[Next step]
[5 · Payments & plans](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/05-payments-and-plans/)
:::

# 4 · Email (SMTP)

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/04-email/

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

**Steps at a glance:**
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.
2. **Configure SMTP in the admin panel** — `Admin → Config → SMTP` (or `Settings → Email`). The human enters the
   password/secret field; the agent fills non-secret fields, clicks the panel test, and checks logs when browser
   automation is available. Inbox confirmation stays human-owned unless the operator explicitly shares that mailbox session.
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`.
4. **Review email templates & hygiene** — audit the app's email templates and sender hygiene, so customer-facing
   messages are branded, deliverable, and not leaking vendor defaults.

:::note[User part + done-when]
**🔀 User part** — the human supplies SMTP secrets and confirms any real inbox delivery. After the session and secret fields are handled, the agent fills non-secret SMTP fields, clicks the panel's **"Test SMTP"** button, checks logs/banners, runs the source greps, and writes the `.env` fallback.

**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. &nbsp;·&nbsp; **⏱ 20–45 min** &nbsp;·&nbsp; 🔀 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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/) 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.

Before editing mail settings, read `Zaj-PROJECT.md` for the selected environment, mail provider, from-address, vault item pointer, and whether runtime mail config is DB-owned or `.env`-owned. Update those non-secret facts after verification; never store SMTP passwords there.

:::caution[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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/), 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](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/02-survey-and-brand/)) already flagged whether the vendor ships a `CustomConfigProvider`; confirm it now.

```mermaid
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"]
```

<Steps>

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

   ```bash
   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.

</Steps>

:::danger[Froiden family — the "APP_ENV changed" banner LIES]
SocietyPro / 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:

:::tip[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 mixed browser flow: human-owned secret fields, agent-owned non-secret fields, save/test clicks, banner checks, and log verification when browser automation is available.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** enters the SMTP password/secret and verifies any real mailbox delivery. 🤖 **Agent** fills the non-secret fields, clicks Save/Test SMTP, reads the resulting banner/logs, and records evidence when browser automation is available.
:::

<Steps>

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 — the human enters the password from the vault; the agent never types or reads it |
   | Encryption | `TLS` (587) / `SSL` (465) |

   - ✅ All fields are filled from real credentials; the password was human-entered from the vault and never exposed to the agent.

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.

</Steps>

:::note[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.

<Steps>

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

   ```bash
   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.

</Steps>

### 4. Review email templates & hygiene

<Steps>

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.

</Steps>

## 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** — human entered secrets; agent saved/tested the panel when browser automation was available; "Test SMTP" passes and the dashboard error banner is gone.
- [ ] **👤 Reset email received** — a real password-reset email arrived end-to-end, or the mailbox-only check is tracked with owner/trigger.
- [ ] **🤖 `.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.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the mail provider, from-address/name, runtime source of truth (admin DB vs `.env`), vault pointer, and last verified date without secrets.

:::next[Next step]
[5 · Payments & plans](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/05-payments-and-plans/)
:::