mailinapp
Documentation menu

KPI scorecard block

One big headline number for the metric an email is reporting on — revenue, signups, NPS, whatever the recipient should see first. It's the block most digest and dashboard emails lead with, usually three of them in a row above a chart.

How it works

A scorecard is a label, a big value, an optional trend indicator, and an optional sparkline — in that visual order, top to bottom. The value and label are always rendered as real HTML text, at whatever font size and color you've set; nothing about reading the headline number depends on an image loading. Only the sparkline is a rendered PNG, and even then it's decoration on top of a number that's already legible without it.

The trend indicator (the "Δ") only appears once both a previous value and a trend direction are set — the block treats them as one authored unit, not two independent optional fields, so there's never an ambiguous state where a Δ percentage shows with no arrow to explain which direction is good. The percentage itself is always computed from value vs. previousValue; the direction (up/down/flat) is not inferred from whether the number went up — you set it yourself. This matters because "went up" isn't always good news: a support-ticket count or a churn rate going up is bad, and a scorecard reporting on either needs to say so with a down-colored arrow even though the raw number increased. The arrow's color follows the direction you chose (green for up, red for down, amber for flat) using the project's own status colors, not a hardcoded palette.

The sparkline is a small trend-line image plotting whatever values you type into the Sparkline values field (or, in bound mode, the bound field's per-row values, capped at 60 points) — it only renders once there are at least two points to draw a line between. Its line color follows the Δ's color when there is one, so a downward, serious-looking trend literally reads red at a glance; with no Δ configured it falls back to the project's brand color.

Configurable fields:

  • Label — the metric's name, plus its own color and font size.
  • Value — the headline number, as a literal string (so it can also hold a merge tag).
  • Format — Number, Currency (USD, no decimals), or Percent — controls how value and previousValue are formatted for display, not how they're stored.
  • Previous value — the comparison point for the Δ. Required alongside Trend direction for any Δ to show at all.
  • Trend direction — None / Up / Down / Flat. Drives both the arrow glyph and its color.
  • Sparkline values — a manually typed list of numbers plotted left to right.
  • Background color, padding, border, border radius on the card.
  • Independent color/font-size pairs for the value text and the label text.

Beyond authored values, a KPI scorecard can bind its value to a connected data source (a Value field plus an aggregate — Sum, Average, Count, or Latest row — collapsing every bound row into the one headline number) or to a past campaign's own response results. Binding replaces value (and the sparkline's source data) only — previousValue and trendDirection always stay author-typed, since a bound "previous" number would need historical snapshots this schema doesn't keep. See Binding charts to real data for the full mechanics of both modes.

Examples

Subject

Your July performance summary

The fastest way to see this block in context is starting a project with the Dashboard purpose: it seeds a "Weekly performance" heading, three KPI scorecards (Revenue as currency with an upward Δ, New signups as a plain number with an upward Δ, Conversion rate as a percent with a flat Δ) laid out side by side in columns, followed by a bar chart — the Dashboard grid preset. It's a starting point with plausible example numbers, not bound to anything until you connect it.

A weekly ops digest might lead with three scorecards — open tickets, average response time, CSAT — each with a Δ against last week, giving the reader the headline before they scroll to any chart. A post-campaign report can use a single large scorecard for "Total revenue" bound to that campaign's product-block orders via a data-source aggregate, with a sparkline showing the day-by-day run-up to send. A subscription business's monthly recap might scorecard MRR, churned accounts, and net new accounts together — three cards, three different Δ directions, each colored correctly because the direction is authored per card rather than guessed from the sign of the change.

What the static fallback looks like

<div style="margin:12px 0;padding:16px;background-color:#ffffff;border-radius:8px">
  <p style="margin:0 0 4px;font-weight:600;font-size:13px;color:#6b7280">Revenue</p>
  <p style="margin:0 0 6px;font-weight:700;font-size:32px;color:#111827">
    $24,800
    <span style="font-size:14px;font-weight:600;color:#16a34a">▲ +18.1%</span>
  </p>
  <img src="https://mailinapp.com/api/analytics/chart?d=eyJ0eXBlIjoi...&s=3f9a2b1c..." width="160" height="40"
       alt="Trend sparkline, upward: 18000, 19500, 21000, 24800"
       style="display:block;max-width:100%;height:auto;margin:4px 0" />
  <p style="margin:4px 0 0;font-size:11px;color:#9ca3af">Revenue — $24,800 — ▲ +18.1% vs previous</p>
</div>

The value, label, and Δ are all real text before the sparkline <img> even appears; the small gray line underneath repeats the same three facts as plain text, so the card is fully readable with images off.

Related