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).
• 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 with 4 trigger cards, a flags panel, 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.

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:

• Servicios (notification:send) — four trigger cards, a debug/ignoreDayRestriction/useEmailLimit flags panel, a transport status header. 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.

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.

Currently one key: notification.adminEmails (summary recipients), edited on the Servicios tab, gated on setting:manage (ADMIN — above notification:send, because redirecting the audit summaries is how someone would stop them being read). 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.

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.

Cron (future)

The four service methods (runOutstandingPayments, runPaymentConfirmation, runAccountStatus, runTrustConfirmation) are the entry points. A future @nestjs/schedule cron would call them on the legacy cadence (Job 3 on Mon/Wed/Fri, Job 2 daily, Jobs 1 + 4 ad-hoc). Pattern matches OpsService's single-running-job guard: one email_notification_sweep OpsJob per run, with its log streamed to OpsJob.log.

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.