Customer communications inventory

Every automated email a customer, PRO, or dealer can receive from Heatwave —
what fires it, when, where the template lives, and how much it actually sends.

Volumes are the trailing 12 months from production (communications joined to
email_templates), measured 2026-07-25. They are the fastest way to tell a live
path from a dead one.

Two independent send systems. Read this first or the inventory won't make
sense — roughly 90% of customer mail comes from the first one, and its
templates are not in the repo.

The two systems

1. DB-backed templates (`EmailTemplate` + `system_code`)

The dominant path. The body, subject, and styling live as rows in the
email_templates table, not as files in the repo. Application code addresses
a template by its stable system_code and hands it to CommunicationBuilder,
which resolves recipients, applies EmailPreference suppression, renders the
Liquid-style {{ }} merge fields, and writes a Communication +
CommunicationRecipient row per address.

# app/services/quotes/quote_expiration_message.rb — the canonical shape
EMAIL_TEMPLATE_QUOTE_EXPIRATION = 'QUOTEEXPIRATION'
@email_template = EmailTemplate.find_by(system_code: EMAIL_TEMPLATE_QUOTE_EXPIRATION)

CommunicationBuilder.new(
  sender_party:, recipient_party:, template: email_template,
  resource: quote, recipient_contact_points: emails,
  transmit_at: 1.hour.from_now
).create

Editing a template means editing production data, not shipping code — CRM at
/crm/email_templates/:id (config/routes/crm.rb:1416). This is deliberate:
marketing and support change copy without a deploy. The tradeoff is that the
usual safety net (review, CI, rollback) doesn't apply, so the guardrails have to
live in the editor instead — see
Merge fields are validated at save time.
system_code is unique and validated
(app/models/email_template.rb). A template carrying one may be active or
archived, never draft — code resolves it by that code, so a half-finished
draft must not be reachable. Archiving is how a code-addressed template is
retired without deleting the row or its communications history; if the send
path resolves one anyway, EmailTemplate#assert_sendable! reports to AppSignal
rather than dropping the email.

94 templates carry a system_code. Their category drives suppression:

Category	Templates	Suppressible
`transactional`	77	No — see below
`announcements`	9	Yes
`reviews`	4	Yes
`promotions`	3	Yes
`newsletters`	1	Yes

Suppression is EmailPreference.can_receive_email_of_category
(app/models/email_preference.rb:79), which resolves disable_#{category} on
the preference row. email_preferences has opt-out columns for reviews,
promotions, newsletters, announcements, events, webinars, and
email_tracking — there is no disable_transactional column.

So transactional mail is always deliverable, which is correct. But note how it
gets there: respond_to?(:disable_transactional) returns false, and the method
treats an unrecognised category as allowed. The guarantee is implicit, not
enforced. Adding a disable_transactional column for any reason would
instantly make every order confirmation, invoice, and receipt suppressible, with
no other code change and no test to catch it.

Two more defaults worth knowing: no EmailPreference row at all means
everything is allowed, and events/webinars opt-outs exist but no
system_code template uses those categories (they're campaign-only).

Merge fields are validated at save time

Bodies render through the liquid gem, and the render path deliberately does
not use strict variables (app/lib/liquid/renderer.rb) — a template already
in the database must still send, so an unknown name resolves to an empty string
rather than raising mid-send.

That leniency used to mean a typo shipped silently. {{receipt_reference_number}}
sat in the Check-payment branch of PURCHASE_RECEIPT and AUTH_RECEIPT — every
sibling branch used {{receipt_reference}}, and nothing ever set the longer
name — so customers paying by check received a receipt with a blank "Ref:" line.
No error, no log entry.

Two gates now catch that class of bug at save time:

Check	Scope	Behaviour
Liquid syntax	All templates	Blocks save
Unknown merge field	`system_code` templates only	Blocks save

Syntax. Liquid::ParseEnvironment.parse! raises; .parse stays forgiving
for the render path. (The validation existed before but was dead code —
.parse swallowed Liquid::SyntaxError internally, so the model's
rescue Liquid::SyntaxError was unreachable.)
Merge fields. EmailTemplate::MergeFields holds the allowlist: globals
from CommunicationBuilder#merge_options, the resource under its own model
name, and per-system_code extras. Campaign templates are exempt — their
merge options are ad-hoc per sender, so there's no knowable allowlist.

When a developer adds a new merge option, register it under that
system_code in BY_SYSTEM_CODE or the template that uses it won't save. The
validation error says so explicitly.

2. ActionMailer classes

29 mailers in app/mailers/, views in app/views/<mailer>/. These ship with the
code and are reviewable in a PR. The large majority are internal-staff
notifications, not customer mail — delivery_mailer, orders_mailer,
internal_notification_mailer, internal_reports_mailer,
payment_reconciliation_mailer, and most of rma_mailer all address reps and
ops. The genuinely customer-facing ones are called out in the inventory below.

Inventory — customer-facing, by lifecycle

Sends = trailing 12 months. — means the template exists but sent nothing in
that window (see Dormant templates).

Quote & pre-sale

Code	Trigger	Timing	Sends
`QUOTE`	Rep sends a quote	On demand	10,522
`QUOTEEXPIRATION`	`Quotes::QuoteExpirationMessage`	Cron Tue/Wed/Thu 03:25 CT, 8-day forward window; one send per quote via `expiration_notice_sent`	2,354
`OPPORTUNITY_RECEIVED`	`Opportunity` created from a web quote request	Immediate	444
`QUOTE_ONLINE`	Self-serve online quote	Immediate	298
`PLAN_REQUEST_CONF`	`RoomConfiguration` plan request	Immediate	40
`QUOTE_SMARTSERVICE`	SmartService quote	Immediate	—

QUOTEEXPIRATION is the only quote mail on a schedule. It fires ~3–7 days before
quotes.expiration_date, which is itself created_at + 60 days or the earliest
attached coupon expiry, whichever is sooner
(Quote#calculate_expiration_date). See config/sidekiq_production_schedule.yml
→ send_quote_expiration_emails.

Order & payment

Code	Trigger	Timing	Sends
`ORDER_TRACKING`	Shipment tracking registered (`Order`)	On carrier pickup scan	5,563
`ONLINE_ORDER_CONFIRM`	Web order placed (`Order`)	Immediate	2,676
`ORDER_PAYMENT`	`OrdersController` — payment pending	Immediate	1,320
`ORDER_BO_NOTIFY`	`Order::BackOrderClientNotification`	Cron Mon–Fri 06:00 CT (`backorder_reminder_worker`)	478
`ORDER_PICKUP`	Order ready for will-call (`Order`)	Immediate	301
`ORDER_INVOICED`	Post-invoice tips email	Immediate	—

Billing & receipts

Code	Trigger	Timing	Sends
`INVOICE`	`FinancialsMailer`	On invoice issue	4,228
`PURCHASE_RECEIPT`	Payment captured	Immediate	2,689
`AUTH_RECEIPT`	Card authorization	Immediate	716
`STATEMENTOFACCOUNT`	Statement run	On demand	187
`CREDITMEMO`	Credit memo issued	Immediate	52
`INVOICE_PAYMENT`	`InvoicesController`	Immediate	10
`WIRE_TRANSFER_INFO`	`Payment` — wire selected	Immediate	8
`COLLECTIONS_30`	Invoice 30d overdue	Dunning	6
`COLLECTIONS_DUE`	Invoice past due	Dunning	2
`COLLECTIONS` / `COLLECTIONS_90`	Dunning ladder	Dunning	—

The collections ladder is near-dormant (8 sends in 12 months across four
templates) and none of the four resolve to a caller in app/ or lib/ — worth
confirming whether dunning is still driven from Heatwave at all.

Returns (RMA)

Code	Trigger	Timing	Sends
`RMA`	RMA created	Immediate	1,232
`RMARC`	`Rma` — return being processed	Immediate	956
`RMA_REMINDER_1`	`Returns::SendFirstReminder`	Advance-replacement invoice 10 days unpaid, RMA still `awaiting_return`. Cron daily 12:00 CT (`rma_reminder_worker`)	386
`RMAINSPECT`	Return received at warehouse	On receipt	345
`RMA_REMINDER_2`	`Returns::SendSecondReminder`	Same, at 20 days	220
`RMA_CHARGE`	`Returns::SendChargeNotice`	Same, at 30 days	107
`RMAITEMREJECTED`	`RmaItem` evaluation failed	On inspection	4

The 10/20/30-day ladder lives in Returns::ReminderLadder. It matches invoices
at least N days old that haven't been notified at that stage, marked per-RMA
on rmas.reminder_1_sent_at / reminder_2_sent_at / charge_notice_sent_at —
the same shape as quotes.expiration_notice_sent. Stages are strictly ordered:
stage N only fires once stage N-1 has, so an invoice already 30 days old can't
trigger all three notices in one run.

It previously matched document_date = N.days.ago.to_date exactly, so a
single missed daily run dropped that day's cohort permanently, with no catch-up
and nothing logged.

Cart recovery & loyalty

Code	Trigger	Timing	Sends
`ANNIVERSARY25OFF`	`Customer::CustomerAnniversaryMessage`	Cron daily 03:30 CT	5,523
`ABANDONED_CART`	`Order::SendAbandonedCartEmails`	Cart idle >24h and <7d	764
`ABANDONED_CART_REM`	Same service, second touch	Cart idle >48h and <7d	38
`ABANDONED_CART_REM_2`	Final cart touch	Within the 7-day window	31

AbandonedCartReminderWorker runs every 30 minutes, not on a cron — the
24h/48h/7d bounds in app/services/order/send_abandoned_cart_emails.rb:37,50 do
the gating. The 7-day upper bound means a cart older than a week is never
recovered.

PRO / installer certification

Code	Trigger	Timing	Sends
`CERT_PROGRESS`	`CourseEnrollment` stalled	Cron daily 06:50 CT (`course_enrollment_worker`)	174
`CERT_EXPIRED`	`Certification` lapsed	Cron daily 06:25 CT (`certification_check_worker`)	17
`CERT_EXPIRES_10`	Certification expiring	10 days before	17
`CERT_EXPIRES_30`	Certification expiring	30 days before	3
`CERT_INS_WARN`	`Certification::InsuranceEscalation`	14 days before card expiry	—
`LIAB_INSUR_EXPIRES10`	Insurance expiring	10 days before	2
`LIAB_INSUR_EXPIRED`	Insurance lapsed	On expiry	3
`CERT_INS_FINAL`	`Certification::InsuranceEscalation`	14 days after expiry	3
`CERT_INS_LAPSED`	Suspension notice	14 days after final notice	—
`COURSE_EXAM_PASSED`	Exam passed	Immediate	1
`NEW_INSTALLER` / `NEW_CERT_REMINDER`	Certification granted / reminder	—	—

The insurance ladder is a clean, documented escalation —
WARN_LEAD_DAYS = 14 → FINAL_LEAD_DAYS = 14 → EXPIRE_GRACE_DAYS = 14
(app/services/certification/insurance_escalation.rb:31-35), driven daily by
CertificationCheckWorker. A separate liability_insurance_check_worker runs
06:10 CT.

Dealer locator

DEALER_INVITE (4), DEALER_CONFIRMED (2), and the deletion ladder
DEALER_SET_TO_DELETE → DEALER_DELETE_IN7DAY → DEALER_DELETED (all dormant)
— every one driven from app/models/locator_record.rb.

Support cases

Case updates reach the customer — they carry the case number in the
subject. The assignment/queue templates with similar names do not; see
Internal-only.

Code	Trigger	Timing	Sends
`SUPPORTCASE_UPDATE`	`SupportCase` updated	Immediate	1,454
`ECOM_TCKT_UPDATE`	Ecommerce ticket updated	Immediate	83

Service appointments (SmartFit)

Driven from SupportCase, but these confirm an appointment rather than report
case progress.

Code	Trigger	Timing	Sends
`SMARTFIT_APPOINTMENT`	SmartFit appointment booked	Immediate	—
`SMARTFIT_CONFIRMED`	Appointment time confirmed	Immediate	— (archived)

Content, reviews & service bulletins

Code	Trigger	Timing	Sends
`BULLETIN_UPDATE`	`Article` service bulletin edited	Immediate	378
`BULLETIN_CREATE`	New service bulletin	Immediate	27
`ORDER_REVIEW_THX`	Review submitted	Immediate	23
`REVIEWIO_COMPANY`	Reviews.io company request	Via `reviews_io_*` workers (feed every 6h, import daily 04:00 CT)	1
`BLOG_UPDATE`	`BlogUpdateWorker`	Cron Mon 14:00 CT	—
`BLOG_CONFIRM`	`BlogSubscriptionMailer` double opt-in	Immediate	—
`REVIEWIO_PRODUCT`, `PRODUCT_REVIEW_THX`, `COMPANY_REVIEW_THX`	Review flows	—	—

Partner / trade (not end-consumer)

INVENTORY_FEED (2,487 — Edi::ResellerInventory::Sender, reseller stock
feeds), PURCHASEORDER (313 — outbound to suppliers), PRICING_TERMS (—),
SPIFF_ENROLL / SPIFF_UPDATE / SPIFF_END (all dormant),
EXPORTED_CATALOG (—).

Rep-composed, not automated

BLANK (7,185), BLANK_REPLY (8,204), and BLANK_TECH (17) are the shells a
rep types into from the CRM. High volume, but a human sends every one — they
belong in this list only so nobody mistakes the volume for automation.

Internal-only — never reaches a customer

Listed so nobody wires a customer onto them. Support/ticket routing —
assignment and queue notices addressed to reps: SUPPORTCASE_ASSIGN (1,659),
SUPPORTCASE_UNASSGND (851), SUPPORTCASE_OPEN (453), ECOM_TCKT_ASSIGN
(170), ECOM_TCKT_UNASSIGNED, ACCT_TCKT_ASSIGN, ACCT_TCKT_UNASSIGNED,
TICKET_UNASSIGNED, NEW_SUPPORT_CASE.

Note the split: the routing templates above are internal, but the case
update templates go to the customer and are listed under
Support cases. SUPPORTCASE_* is not a single audience.

Most app/mailers/ classes are also internal: delivery_mailer,
orders_mailer (profit review, release authorization, insufficient payment),
internal_notification_mailer, internal_reports_mailer,
payment_reconciliation_mailer, problematic_delivery_alert_mailer,
express_hold_alert_mailer, oauth_credential_mailer, brain_maintenance_mailer,
scheduler_admin_mailer, video_transcription_mailer, and the reporting half of
rma_mailer.

Customer-facing mailer classes: account_mailer (password changed, email
changed, username reminder, account created), blog_subscription_mailer
(confirmation), financials_mailer (invoice, tax exemption), privacy_mailer,
warranty_mailer, scheduler_booking_mailer, training_mailer.

Dormant templates

32 of the 94 system templates sent nothing in 12 months. Some are genuinely
seasonal; others are dead paths whose calling code was removed.

Ten have been archived, selected on two signals — no reference anywhere in
app/ or lib/, and no send in two years:

Never sent: BLOG_COMMENT, COLLECTIONS, NEW_DEALER_TOOL,
NEW_SUPPORT_CASE, ORDER_INVOICED, TICKET_UNASSIGNED
Silent 2+ years: SMARTFIT_CONFIRMED (2023-10), COMPANY_REVIEW_THX
(2024-01), PRODUCT_REVIEW_THX (2023-10), COLLECTIONS_90 (2024-08)

Three deliberately left active despite having no resolvable caller —
COLLECTIONS_30 and COLLECTIONS_DUE both sent in May 2026, and
ORDER_REVIEW_THX in November 2025. Something triggers them that a code grep
doesn't find (a rake task, a CRM action, an operator). Send history beats static
analysis here; don't archive them on the grep alone.

Reproduce the check:

psql "$POSTGRES_REPLICA_URI" -c "
  SELECT et.system_code, count(c.id) AS sends_12mo
  FROM email_templates et
  LEFT JOIN communications c
    ON c.email_template_id = et.id AND c.transmit_at >= now() - interval '12 months'
  WHERE et.system_code IS NOT NULL AND et.system_code <> ''
  GROUP BY et.system_code ORDER BY 2 DESC;"

Delivery, tracking & measurement

All outbound mail goes through SendGrid subusers. Per-recipient state lives
on communication_recipients.state (processed → delivered → opened →
clicked, or bounced/dropped/deferred), updated by the event webhook at
/webhooks/v1/sendgrid → WebhookProcessors::SendgridProcessor →
Communication::EventParser.

Two traps when measuring engagement:

webhook_events retains only ~3 months. Anything longer must come from
the durable communication_recipients.state, or open rates collapse toward
zero for older sends.
state is terminal, not cumulative. A recipient who clicked reads
clicked, not opened — count opens as state IN ('opened','clicked').
machine_open flags Apple MPP-style opens.

The engagement rollup

Counts survive the 3-month retention because recipient state is durable. Event
timing does not — and timing is what showed Saturday quote-expiration
notices sitting ~50h before being read against 6–8h on weekdays. That analysis
was only possible inside the retention window; past it, the data was gone.

EmailEngagementRollupWorker (daily, 04:00 CT) writes per-template daily
metrics to email_template_data_points, the same fact-table shape as
site_map_data_points and catalog_data_points, so the whole read/trend API
comes from Models::DataPointMetrics.

	Metrics	Why
`DURABLE_METRICS`	sends, delivered, opened, clicked, bounced, dropped, unsubscribed, spammed, machine_opened	Recomputable from recipient state at any time
`PERISHABLE_METRICS`	total_opens, total_clicks, median_hours_to_open, opened_within_24h	Derived from `webhook_events` — unrecoverable once they age out

The rollup upserts on (email_template_id, metric_type, period, reference), so
re-running a day overwrites rather than duplicates; backfilling is a loop over
dates. History accrues from launch — it can't be reconstructed retroactively
beyond the current retention window, so the sooner it runs the more you keep.

Open/click tracking is disabled per-recipient when EmailPreference.can_track_email?
is false (CNIL/Garante prior-consent compliance).

Adding a new automated communication

Create the EmailTemplate row in CRM with a new unique system_code
(≤20 chars) and the right category — the category is the customer's only
opt-out lever.
Reference it from code by system_code, never by id.
Send through CommunicationBuilder so suppression, merge fields, tracking
consent, and the Communication audit trail all apply.
If it's scheduled, add the entry to config/sidekiq_production_schedule.yml
and make the query's forward window wider than the longest gap between run
days — see Quotes::QuoteExpirationMessage::NOTICE_WINDOW and its test for
the failure mode.
Add a row to this inventory.

.agents/skills/mailers/ — ActionMailer conventions
.agents/skills/background-jobs/ — worker + schedule patterns
doc/infrastructure/README-POSTFIX.md — inbound/relay MTA