Problem: every mailer had become its own small application
Operational emails had grown independently: different scripts, layouts, recipient handling, metric definitions and failure behaviour. Some sent raw tables, some embedded business logic, and silence could mean healthy, failed or simply not scheduled. Maintaining them meant rediscovering the same delivery problems repeatedly.
Pigeon reorganised that last mile. Analytical services owned calculations and persisted publishable results. Pigeon owned run validation, report composition, recipient-safe delivery and a common visual language.
This article is intentionally public-safe. It explains the engineering decisions and lessons without exposing customer data, proprietary prompts, internal identifiers, operational commands or confidential decision thresholds.
- RUNRead a completed analytical execution
- GATERequire success and explicit publication intent
- COMPOSEBuild summaries, ranked detail and context
- PREVIEWInspect saved HTML without sending
- DELIVERSend to the approved audience and log outcome
Architecture: one reporting layer, many analytical owners
Pigeon did not recalculate anomalies. It consumed a versioned successful run and its published alerts. This prevented the email and dashboard from drifting into different interpretations of the same metric.
A report definition supplied title, summary fields, grouping, row rendering and recipient configuration. Shared delivery code handled the HTML shell, MIME construction, preview mode and failure reporting. New mailers could reuse the operating system without losing the identity of their analysis.
The successful-run gate
Before reading output, Pigeon verified that the analytical run finished successfully and was explicitly marked for publication. A failed run never became an all-clear message. A successful run with no alerts could produce an explicit healthy report, making silence unnecessary as a state.
This contract was the most important part of the system. Formatting can be repaired after one bad email; trust is harder to recover after a green message built from incomplete analysis.
Design and testing under email constraints
The shared template used compact table-based layout and inline styling because email clients do not support the modern web consistently. The hierarchy was predictable: run status, metric summary, severity counts, affected markets, ranked detail and a short interpretation note. Relative bars provided scanability without relying on fragile chart libraries.
Preview and no-send modes rendered the exact message from saved data. This allowed layout, clipping, recipient scope and MIME structure to be checked without production database access or accidental delivery. Test recipients stayed narrow until explicitly expanded.
Result and impact
Pigeon turned scattered mail scripts into a reusable reporting contract. Analysts could focus on the meaning of a signal; operators received consistent state and prioritisation; delivery behaviour became testable once rather than reinvented per project.
The general lesson is that communication is part of system correctness. An analysis is not operationally complete when it writes a row. It is complete when the receiver can tell what happened, whether the run is trustworthy and what deserves attention next.