jorgecuadros-platform/docs/MASS_EMAIL_NOTIFICATIONS.md

Mass Email Notifications

Modern replacement for the four PHP scripts under email.notifications/send*.php that fired bulk emails off the legacy utility_dbo.email_alert_log table. Lives in this codebase from massive-email-notification onward; the PHP scripts stay operational until the office flips over.

Why

The legacy scripts did three things this app needed to keep doing: send outstanding-payment reminders, send payment-confirmation letters, and fire account-status alerts (red and yellow). They also sent a fourth trust-payment confirmation tied to TRUSTHFEE. Each was a separate CGI script the office hit manually or via cron, talking to utility_dbo over the same mysqli connection as the rest of the portal.

The unified schema (see PLAN.md and docs/INSURANCE_FEATURES_SPEC.md) folded datosfreak and TRUSTHFEE into customers + transactions + trust_accounts, so the scripts' SQL no longer maps to anything. Rather than maintain parallel sync code to keep utility_dbo populated, this feature ports the four jobs onto the unified data and writes its own log.

What ships

• apps/api/src/mail/ — outbound mail transport. Amazon SES (matches the StorageService env-driven optional-client pattern). Dev falls back to stdout logging so a fresh checkout can exercise the jobs without SES credentials.
• apps/api/src/notifications/ — the four jobs (outstanding, payment-confirm, account-status, trust-confirm), each a public service method + a POST /notifications/{slug} HTTP endpoint gated on the new notification:send ability (MANAGER).
• apps/api/src/notifications/notification-schedule.service.ts (+ its own module) — the cadence of both automatic sweeps, stored in app_settings and installed into SchedulerRegistry at boot. See "Scheduled runs" below.
• packages/database/prisma/migrations/20260801200000_mass_email_notifications/migration.sql — two new tables (email_notification_log, account_status_history) with enums and FKs to customers.
• apps/web/src/app/notificaciones/ — admin page: a shared flags panel and schedule editor above the tabs, then per-tab trigger cards, a transport-status header, and a paginated log browser.

Job semantics

Preserved from the PHP originals (see ~/Documents/Claude-Memory/email-notifications-spec.md):

Job	Recipients	Subject	Response key
1. Outstanding payments	Customers with ≥1 outstanding Transaction (amount<0)	"Jorge Cuadros - Outstanding Payments"	result:"success", notificationType:"sendPaymentConfirmation"
2. Payment confirmation	Customers with a credit in last 24h	"Jorge Cuadros - Payment Confirmation"	request:"success", notificationType:"sendPaymentConfirmation"
3. Account status	All customers with a balance; yellow/red thresholds	"Jorge Cuadros - Account Status Alert"	request:"success", notificationType:"sendAccountStatus"
4. Trust confirmation	Customers with TrustAccount + recent TRUST-domain credit	"Jorge Cuadros - Trust Payment Confirmation"	request:"success", notificationType:"sendTrustPaymentConfirmation"

Wire shapes match the PHP originals byte-for-byte so anything downstream that scrapes notificationType:"sendPaymentConfirmation" keeps working. Job 1 reports result (not request) and notificationType literally sendPaymentConfirmation — these are the legacy quirks, preserved.

Day gates (Job 3 only)

• Yellow ("DEBAJO DEL TIPO"): Wed only (or ignoreDayRestriction).
• Red ("EN ROJO"): Mon/Wed/Fri only (or ignoreDayRestriction).
• A customer who is red on Tuesday is logged as SKIPPED_GATE until Wed, when both checks can fire on the same row.

Threshold logic (Job 3)

The PHP used datosfreak.TIPO (50/100/200/300/500) and a hardcoded threshold table. The new schema encodes this as Customer.minimumBalance:

• Yellow: 0 ≤ balance < minimumBalance
• Red: balance < 0

Per-currency balance uses BillingService.balances() semantics (signed SUM(transactions.amount), voided + outstanding excluded), so a yellow/red alert always lines up with what the receivables worklist shows staff. The customer-servicing letter reports in USD because the legacy letter was always USD; the union of balanceUsd and balanceMxn is reported per-customer, never collapsed (see BillingService.balances()).

Rate limit (Job 3 only)

useEmailLimit=true enables a vestigial throttle: pause the sweep 1h after 100 sends. Off by default; SES does not need it.

Send flags

The three flags are platform-wide, not per-tab. They live in the /notificaciones shell above the tabs (NotificationFlagsCard), and the shell passes them to both halves.

Flag	Applies to	Effect
debug	everything	Rewrites every recipient to DEBUG_RECIPIENT (rmancinas@freakma.net), tags the log row debug: true, sends with xTracking: "debug".
ignoreDayRestriction	Job 3 only	Bypasses the Wed / Mon-Wed-Fri gates.
useEmailLimit	Job 3 only	The vestigial throttle above.

debug used to exist only on the servicios side, which meant there was no way to test a renewal aviso without mailing a real customer. On the pólizas path it now does three things beyond diverting the mail, all for the same reason — the customer was not notified, so nothing may claim they were:

1. no RenewalNotice row is written, so the aviso stays in the pending list;
2. the sweep's lastSuccessfulAt is not advanced, because renewalWindow() uses it to widen the window over missed days — advancing it after a test run would narrow tomorrow's window and drop those candidates for good;
3. the send response carries debug: true and the address actually used, so the UI says "prueba enviada … el cliente no ha recibido nada" rather than claiming a delivery.

Flags are per-visit UI state and are never persisted. A stored debug would survive a reload and silently swallow real customer mail for as long as nobody noticed. For the same reason the automatic runs below ignore them entirely and always send for real.

Tables

email_notification_log

One row per send attempt (sent, failed, skipped). Carries the rendered body verbatim so a customer reply quoting an old email can be traced to the exact letter sent. SES MessageId stored for bounce/complaint correlation.

Indexes: (sendDate), (notificationType, sendDate), (customerId, sendDate).

This table is not job-specific. Insurance renewal avisos (RenewalsService, see RENEWAL_NOTICES.md) write here too, as notificationType = RENEWAL_NOTICE / servicio = POLICIES — one send history for the whole platform rather than one per feature. NotificationLogService is the only writer; anything that sends mail goes through it.

level is therefore per-type and cannot be read without its notificationType: 0/1 (yellow/red) on ACCOUNT_STATUS, the aviso generation 1/2/3 on RENEWAL_NOTICE, null elsewhere. On the web side notificationLevelLabel() is the only place that branch lives.

Renewals keep their own renewal_notices row as well. The two are not redundant: renewal_notices is gating state (one row per policy+generation, "already notified" — it drives the pending list), while this log is history (every attempt, including the failures and no-email skips a gating row cannot represent).

account_status_history

Mirrors the legacy utility_dbo.send_account_status_history table: (customerId, customerName, customerEmail, tipo, tCambio, balance, solicitado, level). tipo is the literal "DEBAJO DEL TIPO" or "EN ROJO" string the PHP used. solicitado keeps the legacy formula (0 - TIPO - BALANCE) even though it double-subtracts; downstream reports depend on the exact figure.

Indexes: (sendDate), (customerId, sendDate), (level, sendDate).

Environment

SES_REGION=us-east-1
SES_ACCESS_KEY=...
SES_SECRET_KEY=...
SES_FROM=mail@jorgecuadros.com
SES_FROM_NAME=Information Server
SES_CONFIGURATION_SET=...      # optional
NOTIFICATION_ADMIN_EMAILS=rmancinas@freakma.net,mpulido@freakma.net  # fallback only

NOTIFICATION_ADMIN_EMAILS is no longer the source of truth. The summary recipients are edited in the UI and stored in app_settings; the env var is the fallback for a deployment where nobody has saved them yet. See "Operator settings" below.

Without SES_* the API still boots and MailService falls back to stdout in dev (NODE_ENV !== "production"). In production every send throws ServiceUnavailableException and the row is recorded as FAILED.

These are runtime config — read at container boot, never baked into the image. For the Portainer deployments they are set as Gitea repo secrets and injected into the stack env by the env_data block of .gitea/workflows/deploy-galactus.yml (and deploy.yml), exactly like DATABASE_URL and SESSION_SECRET. Unlike most secrets there they carry no _GALACTUS suffix: one SES identity serves every deployment.

They are optional to deploy — the preflight only warns — but the production image sets NODE_ENV=production, which disables the stdout dev fallback, so a blank SES config makes every send fail loudly rather than quietly going nowhere.

UI

/notificaciones, two tabs over the one log.

Above the tabs, owned by the shell because both halves are subject to them:

• Flags del envío — the three flags above.
• Programación de envíos — the cadence of both automatic sweeps (setting:manage to edit; everyone can see when the next run is).

Then per tab:

• Servicios (notification:send) — an "Ejecutar todos" card, four trigger cards, a transport status header, and the summary-recipients setting. Reads the CUSTOMERS + TRUST slice.
• Pólizas (renewal:send) — pending avisos and the manual sweep. Reads the POLICIES slice.

Both render the same NotificationLogPanel ("Registro de envíos"), which filters by servicio and by view (todos / enviados / fallidos / omitidos). STAFF users see the Servicios log read-only.

Both mass actions ("Ejecutar todos" and the pólizas sweep) confirm before firing only when debug is off — that is the case where real customers receive mail, and a confirm on every click trains people to dismiss it.

API surface

Method	Route	Ability
POST	/notifications/outstanding-payments	notification:send
POST	/notifications/payment-confirmation	notification:send
POST	/notifications/account-status	notification:send
POST	/notifications/trust-payment-confirmation	notification:send
POST	/notifications/run-all	notification:send
GET	/notifications/log, /notifications/stats	authenticated
GET	/notifications/settings/admin-emails	authenticated
PUT	/notifications/settings/admin-emails	setting:manage
GET	/notifications/settings/schedule	authenticated
PUT	/notifications/settings/schedule/:kind	setting:manage

Every trigger accepts the flags as body or query string — the PHP scripts took both (STDIN vs HTTP-CGI) and parity was cheap. The pólizas endpoints (POST /renewals/sweep, POST /renewals/send) accept debug only; the other two flags are estado-de-cuenta concepts and are not accepted there rather than being silently ignored.

Operator settings

app_settings holds the configuration staff change without a redeploy. SettingsService resolves every key db → env → default, and reports which of the three a value came from so the UI can say so. Adding a key means adding a typed accessor there, not a generic getter.

Keys today:

Key	Edited on	Notes
notification.adminEmails	Servicios tab	Summary recipients, comma-separated.
notification.schedule.servicios	shell	JSON cadence of the automatic run-all.
notification.schedule.polizas	shell	JSON cadence of the renewal sweep.

All three are gated on setting:manage (ADMIN — above notification:send, because redirecting the audit summaries is how someone would stop them being read).

notification.adminEmails is read on every job rather than cached, so an edit takes effect on the next sweep with no restart. An empty saved list means "nobody" and deliberately does not fall through to the env.

The two schedule keys have no env rung on the db → env → default ladder: a cadence was never an environment variable (it was a @Cron literal in the source), so the only two sources are the operator's row and the shipped default. A row that fails to parse is logged and treated as absent — a bad JSON blob must not take the scheduler down with it.

Credentials do not belong here. SES keys, DATABASE_URL and S3 config stay in the environment: they are deployment identity, they must exist before the app can reach its own database, and a table only widens who can read them.

Scheduled runs

Both halves run themselves on an operator-editable cadence. Nothing about the schedule is in the source any more:

Kind	Handler	Default	Was
servicios	NotificationsService.scheduledRunAll() → all four jobs in order	off, 07:00 Mon/Wed/Fri when enabled	nothing — the four jobs were click-only
polizas	RenewalsService.scheduledSweep()	on, 06:00 daily	@Cron("0 6 * * *") in renewals.service.ts

The defaults preserve exactly what each half did before: pólizas keeps its 06:00 sweep, servicios stays off. A default that starts mailing 260 customers on its own after a deploy is not a default, it's an incident.

How it works

NotificationScheduleService owns both cadences. The services that own the sweeps register a handler in onModuleInit:

await this.schedule.register("polizas", () => this.scheduledSweep());

The schedule service then compiles the stored value to a cron expression ({hour, minute, weekdays} → m h * * dow, empty weekdays = *) and installs a CronJob in SchedulerRegistry under notification-schedule:<kind>, in America/Tijuana. Saving from the UI re-reads the row, removes the old job and installs the new one — no restart, which was the whole point.

Handlers are registered rather than injected because NotificationsModule and RenewalsModule both need this service and neither may import the other. It lives in its own NotificationScheduleModule for the same reason as NotificationLogModule.

cron is a direct dependency of apps/api, not just a transitive one of @nestjs/schedule: pnpm's strict layout does not hoist it, so import { CronJob } from "cron" fails to resolve without it.

What a scheduled run does not do

• It never uses the UI flags. No debug (so a forgotten test toggle cannot silently stop customer mail), and no ignoreDayRestriction — an automatic run on the operator's own cadence is exactly the case the Mon/Wed/Fri gate was written for, so bypassing it would mail the red list every scheduled day.
• It does not guard against multi-replica double-fire. The pólizas sweep has always had its own DB lock (scheduled_job_states, taken in RenewalsService.acquireLock); the servicios run-all has no equivalent and relies on the deployment being single-replica, which it is today on galactus. Adding one means the OpsService single-running-job pattern — a DB row, not an in-process flag.

What is intentionally NOT in scope

• Per-recipient preview / HTML view in the UI. The log table shows what was sent; previewing one requires fetching bodySnapshot and rendering HTML in the browser, deferred until a customer-service need surfaces.
• Bounce / complaint webhooks. providerMessageId is captured so a future SNS topic can write back; the integration itself is a separate piece of work.
• Spanish / English body toggle. Legacy letters are English; the legacy customer base is bilingual. Customer has no language preference. Add one when the need is concrete (same open question as INSURANCE_FEATURES_SPEC.md §1.6).
• Importing the legacy utility_dbo.email_alert_log rows. They reference the old NUMid (a stringified double) which no longer maps to a unified customer; an import would be destructive.