Skip to content

Recipes

An alert email

Build the alert with the builder directly; there is no alert template. Each application knows its own facts: what failed, where to look, what to do. The Schwab gateway and the Dagster run-failure sensor both follow this shape.

from common_reports import EmailClient, EmailRenderer, HtmlBuilder
def send_run_failed(job: str, run_id: str, error: str, started: str) -> bool:
b = HtmlBuilder(f"{job} failed")
b.frontmatter(title=f"Run failed: {job}", date=started)
b.status("Failed", tone="danger")
b.text(f"Job: {job}\nRun: `{run_id}`\nStarted: {started}", fmt="kv")
b.callout(error[:1500], tone="danger", title="Error")
b.button("Open the run in Dagster", f"https://dagster.tail005531.ts.net/runs/{run_id}")
b.caption("Links work on the tailnet only.")
email = b.build().render(EmailRenderer(style="modern", preheader=f"{job} failed"))
result = EmailClient.from_env("EMAIL").send(
["ops@example.com"],
f"[NC ALERT] {job} failed",
html=email.html,
attachments=email.attachments,
)
return result.success

Guidelines:

  • Order. Put the status first, then the facts as kv lines, then the error in a danger callout, then one button for the next action.
  • Error length. Cap the error text; a stack trace can run to many kilobytes.
  • Imports. An alert needs only the base install plus gmail; no builders extra.
  • Delivery. Return or log result.success. An alert that failed to send must not look sent.

A daily report with an interactive page attached

from pathlib import Path
from common_reports import EmailClient, EmailRenderer, HtmlBuilder
from common_reports.contracts.builders import Kpi, NumberFormat, PlotFormat, PlotType, Transform
from common_reports.contracts.emails import Attachment
def daily_report(nav, pnl, positions, returns, day: str) -> bool:
b = HtmlBuilder("Daily Report")
b.frontmatter(title="Daily Report", date=day, preheader=f"P&L {pnl:+,.0f}")
b.kpis(
Kpi("NAV", nav, fmt=NumberFormat.DOLLAR),
Kpi("Day P&L", pnl, fmt=NumberFormat.DOLLAR),
Kpi("Positions", len(positions), fmt=NumberFormat.INT),
)
b.section("Performance")
b.plot(
returns,
type=PlotType.CUMULATIVE,
fmt=PlotFormat(strat_cols=("Genesis",), bench_cols=("SPY",), transform=Transform.CUM),
)
b.section("Positions")
b.table(positions)
b.disclaimer()
doc = b.build()
page = doc.to_html(style="modern", date=day).save(Path(f"out/report-{day}.html"))
email = doc.to_email(style="modern")
result = EmailClient.from_env("EMAIL").send(
["partners@example.com"],
f"Daily Report · {day}",
html=email.html,
attachments=[*email.attachments, Attachment.from_path(page)],
)
return result.success

The email shows the “Interactive report attached” box because a file is attached.

Reuse one layout across runs

Build the frame once with {placeholders}, then fill it per run. Placeholders fill text, headings, captions, callouts, status tags, buttons and KPI labels; frontmatter is not filled, so pass per-run titles to the renderer instead.

frame = (
HtmlBuilder("Rebalance")
.heading("Rebalance {date}")
.status("{state}", tone="success")
.text("{orders} orders sent to {broker}.")
.build()
)
doc = frame.fill(date="30 Sep 2026", state="Filled", orders=12, broker="IBKR")
assert not doc.unfilled

Test without sending

Rendering needs no network, so a unit test can assert on the HTML:

doc = HtmlBuilder("t").button("Open the run in Dagster", "https://dagster.example/runs/1").build()
email = doc.render(EmailRenderer(style="modern"))
assert "Open the run in Dagster" in email.html
assert email.manifest["gmail_clip_risk"] is False

To test the send path, patch EmailClient.from_env to return a fake whose send returns SendResult(success=True) or SendResult(success=False, error="..."). Cover both outcomes.