SMTP integration for invites, confirmations and notifications #3

Closed
opened 2026-10-13 18:53:04 +00:00 by ben · 7 comments
Owner

Send transactional email via a configurable SMTP server.

Scope

  • Config via env (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM, TLS mode); no secrets in the repo.
  • Emails: account invite / set password, magic-link login (if chosen), activity assigned, optional 'client finished an activity' notice to the admin.
  • Templated, plain-text + HTML, branded with practice name/logo from config.
  • Outbox table with retry and a dev mode that logs instead of sending.

Acceptance

  • Works against a test SMTP server (e.g. Mailpit) in docker-compose for local dev; failures are retried and visible to admins.

Depends on: RBAC.


Handoff context: the app is being prepared so a counselling practice can self-host it (see README and docs/self-hosting.md). Today the app has no auth by design, two hard-coded decks in shared/cards.json, three fixed columns, and Fastify + SQLite + SSE sync (docs/api.md).

Send transactional email via a configurable SMTP server. **Scope** - Config via env (`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_FROM`, TLS mode); no secrets in the repo. - Emails: account invite / set password, magic-link login (if chosen), activity assigned, optional 'client finished an activity' notice to the admin. - Templated, plain-text + HTML, branded with practice name/logo from config. - Outbox table with retry and a dev mode that logs instead of sending. **Acceptance** - Works against a test SMTP server (e.g. Mailpit) in docker-compose for local dev; failures are retried and visible to admins. Depends on: RBAC. --- Handoff context: the app is being prepared so a counselling practice can self-host it (see README and docs/self-hosting.md). Today the app has no auth by design, two hard-coded decks in `shared/cards.json`, three fixed columns, and Fastify + SQLite + SSE sync (docs/api.md).
Author
Owner

Plan written and reviewed by a High panel (3/3 voices): docs/plans/2026-10-13-14-50_rbac-sign-in-and-smtp-outbox.md. More decisions: counsellors are view-only by default (ADMIN_CAN_EDIT flag); privacy guidance gates real-client use rather than the release; the source PDFs stay private. No code yet.

Plan written and reviewed by a High panel (3/3 voices): `docs/plans/2026-10-13-14-50_rbac-sign-in-and-smtp-outbox.md`. More decisions: counsellors are view-only by default (`ADMIN_CAN_EDIT` flag); privacy guidance gates real-client use rather than the release; the source PDFs stay private. No code yet.
Author
Owner

The outbox needed for magic links and invites landed in 7dd3ea5, after a High review. It covers config validation, the leased worker with backoff and an 8-attempt cap, expiry and redaction of token mail, a 30-day purge, code-only error storage and Mailpit dev compose. Auth enqueues mail through it (7ecfb95).
Remaining in this issue: the owner GET /api/outbox and retry route (slice 5), and the assigned/finished notices. Not deployed.

The outbox needed for magic links and invites landed in 7dd3ea5, after a High review. It covers config validation, the leased worker with backoff and an 8-attempt cap, expiry and redaction of token mail, a 30-day purge, code-only error storage and Mailpit dev compose. Auth enqueues mail through it (7ecfb95). Remaining in this issue: the owner GET /api/outbox and retry route (slice 5), and the assigned/finished notices. Not deployed.
Author
Owner

No outbox changes. Slice 4 (f090295) landed policy enforcement. Slice 5 adds the owner GET /api/outbox and the retry route.

No outbox changes. Slice 4 (f090295) landed policy enforcement. Slice 5 adds the owner GET /api/outbox and the retry route.
Author
Owner

The owner outbox routes landed in b93fd31.

  • GET /api/outbox shows metadata only (no subject, body or token hash) and sanitized error codes. It returns every failed row plus the newest 500.
  • POST /api/outbox/:id/retry requeues a failed non-token row. A failed invite whose body was redacted after 8 attempts is reissued as a fresh invite. Retries are audited.
  • Tested end to end: a failing worker, then the owner's retry, then delivery.

Remaining in this issue: the activity-assigned and client-finished notices. These aren't in the RBAC plan; schedule them with #4. Not deployed.

The owner outbox routes landed in b93fd31. - GET /api/outbox shows metadata only (no subject, body or token hash) and sanitized error codes. It returns every failed row plus the newest 500. - POST /api/outbox/:id/retry requeues a failed non-token row. A failed invite whose body was redacted after 8 attempts is reissued as a fresh invite. Retries are audited. - Tested end to end: a failing worker, then the owner's retry, then delivery. Remaining in this issue: the activity-assigned and client-finished notices. These aren't in the RBAC plan; schedule them with #4. Not deployed.
Author
Owner

The owner Outbox screen shipped in the web client (683a5d3). It lists every email with its status and has a retry button. Docs (4a4d07b) cover SMTP setup with provider examples and outbox troubleshooting in docs/self-hosting.md.
Still open: the activity-assigned and client-finished notices, planned alongside #4. Not deployed.

The owner Outbox screen shipped in the web client (683a5d3). It lists every email with its status and has a retry button. Docs (4a4d07b) cover SMTP setup with provider examples and outbox troubleshooting in docs/self-hosting.md. Still open: the activity-assigned and client-finished notices, planned alongside #4. Not deployed.
Author
Owner

The notices landed in e7e03b9 and are deployed.

  • Activity assigned: an email to the client listing activity titles, enqueued in the same transaction that creates the session. On invite-and-assign the list goes in the invite email instead.
  • Client finished: an email to linked counsellors once per assignment (owners opt in with NOTIFY_OWNER_ON_FINISH), deduplicated through an audit marker.
  • Migration M5: records each notice's recipient and session. The worker re-checks authorization before every delivery attempt and expires and redacts notices that are no longer allowed.
  • Privacy: no notes or card text in any email.
  • Reviews: High (codex, qwen, plus kimi substituting for deepseek), two delta rounds.
  • Production mail: the live host can't send SMTP directly, so mail goes through a relay (operator detail kept in the private runbook). docs/self-hosting.md should note that some cloud hosts block outbound SMTP.

Next: close after checking acceptance against the deployed app.

The notices landed in e7e03b9 and are deployed. - **Activity assigned:** an email to the client listing activity titles, enqueued in the same transaction that creates the session. On invite-and-assign the list goes in the invite email instead. - **Client finished:** an email to linked counsellors once per assignment (owners opt in with NOTIFY_OWNER_ON_FINISH), deduplicated through an audit marker. - **Migration M5:** records each notice's recipient and session. The worker re-checks authorization before every delivery attempt and expires and redacts notices that are no longer allowed. - **Privacy:** no notes or card text in any email. - **Reviews:** High (codex, qwen, plus kimi substituting for deepseek), two delta rounds. - **Production mail:** the live host can't send SMTP directly, so mail goes through a relay (operator detail kept in the private runbook). docs/self-hosting.md should note that some cloud hosts block outbound SMTP. Next: close after checking acceptance against the deployed app.
Author
Owner

Acceptance checked against the repo and the deployed app; closing.

  • SMTP config from env: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM and the TLS mode, validated at startup. No secrets in the repo.
  • Emails: account invite, magic-link sign-in, activity assigned (7dd3ea5, 7ecfb95, e7e03b9) and client finished, with owners opting in through NOTIFY_OWNER_ON_FINISH. Each is plain text plus HTML, with escaped content and the practice name from PRACTICE_NAME. No notes or card text appear in any email.
  • Outbox: leased worker, backoff, an 8-attempt cap, redaction of token mail, and re-authorization before every delivery attempt. MAIL_MODE=log logs instead of sending in development and is refused in production.
  • Acceptance: docker-compose.dev.yml runs against Mailpit. Failed mail is retried and listed on the owner's Outbox screen with a retry button (b93fd31, 683a5d3). Delivery through a real provider is confirmed on the deployed app.
  • Gap: branding uses the practice name only. A practice logo in emails was not built. File it as a separate issue if the practice wants it.
Acceptance checked against the repo and the deployed app; closing. - **SMTP config from env:** `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_FROM` and the TLS mode, validated at startup. No secrets in the repo. - **Emails:** account invite, magic-link sign-in, activity assigned (7dd3ea5, 7ecfb95, e7e03b9) and client finished, with owners opting in through `NOTIFY_OWNER_ON_FINISH`. Each is plain text plus HTML, with escaped content and the practice name from `PRACTICE_NAME`. No notes or card text appear in any email. - **Outbox:** leased worker, backoff, an 8-attempt cap, redaction of token mail, and re-authorization before every delivery attempt. `MAIL_MODE=log` logs instead of sending in development and is refused in production. - **Acceptance:** `docker-compose.dev.yml` runs against Mailpit. Failed mail is retried and listed on the owner's Outbox screen with a retry button (b93fd31, 683a5d3). Delivery through a real provider is confirmed on the deployed app. - **Gap:** branding uses the practice name only. A practice logo in emails was not built. File it as a separate issue if the practice wants it.
ben closed this issue 2026-10-15 02:42:15 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ben/career-values-cards#3
No description provided.