mailinapp
Documentation menu

Rating block

A one-tap feedback question — the block behind CSAT, CES and NPS-style measurement. Structurally it's a poll with a different label set: each score is both a real in-email control and a plain link, so rating works everywhere a poll does, with alerting and a conditional follow-up question layered on top.

How it works

Like the poll block, every score renders with two representations at once: a real <form method="post"> per option wherever in-email posts work, CSS-hidden behind a plain <a href> link into /v/[token]/act for everywhere else — Outlook, or any client that can't submit an in-email form. Whichever path fires, tapping a score records a rate action carrying that value, deduplicated per recipient the same way a poll vote is (a deterministic Firestore doc id means a recipient re-tapping their own confirmation link is a no-op, not a second row), never counted on a bare link prefetch — only on the confirmed action.

Three display styles share this identical submission mechanism, so switching between them never breaks or reshapes existing responses:

  • Stars — the classic row of 3–10 stars (set by scale), each one a tappable score from 1 up to the scale.
  • Numbered scale — a Likert-style row of numbered buttons (also sized by scale), with your own low label and high label captions at each end, e.g. "Strongly disagree" → "Strongly agree".
  • NPS — a fixed 0–10 row, ignoring the scale field entirely (NPS is always eleven buttons), with low/high labels defaulting to "Not at all likely" and "Extremely likely" if you leave them blank.

Two more fields turn a plain rating into an operational signal rather than just a number:

  • Alert threshold (rating ≤ N) — set this and a response at or below it is flagged the instant it arrives: it sets the lowScore flag on the webhook payload and can trigger an in-app email alert to addresses you configure on the project, with no Zapier/Make step required for the basic case. Each rating block sets its own threshold independently — a 1–5 CSAT question and a 0–10 CES question need different cutoffs, and a project can have more than one rating block.
  • Follow-up question, asked when rating ≤ N — an optional free-text prompt (e.g. "What went wrong?") that appears immediately after a qualifying low score is submitted. This only ever appears on the hosted live view, never in mailed HTML — a static email can't branch its content based on the answer just given, since there's no round-trip back to a server mid-read. The follow-up answer lands in your responses as a normal free-text answer attached to the same recipient, under a <question> — follow-up column in the CSV export.

Other configurable fields: question text (with its own color/font size), background color, padding, border, border radius, end-label color/font size, and a chip color override (text and background) applied to every score button. If the project's survey lifecycle close date or response cap has been reached, the live view swaps the chips for inert, grayed-out equivalents with a closed notice — mailed HTML stays static and unaffected, since that check happens at open time.

Responses roll up automatically: response count, average, and a full histogram (the distribution behind the average — a 4.1 average looks very different depending on whether it's mostly 4s or a mix of 5s and 1s), an NPS-specific promoter/passive/detractor breakdown and −100…100 score for NPS-style blocks, plus a response trend chart over time. See CSAT, CES and NPS rollups.

Examples

Subject

How was your recent order?

A post-purchase CSAT question ("How did we do? 1–5 stars") dropped near the bottom of a shipping-confirmation email is the simplest use, especially with a threshold set at 2 so a bad experience routes straight to an alert email instead of sitting unnoticed in a dashboard — see Surveys & NPS feedback for the wider pattern. A quarterly relationship-health check works well as NPS style with a follow-up question at ≤6 ("What would make you more likely to recommend us?"), turning a passive number into an actionable comment from exactly the customers at risk. A support-ticket resolution email can ask a CES-style "How easy was it to get this resolved?" on a numbered 1–7 scale with custom low/high labels, feeding a metric that's specifically about effort rather than satisfaction.

What the static fallback looks like

<div id="em-rating-1" style="margin:12px 0;background-color:transparent">
  <p style="margin:0 0 10px;font-weight:600;font-size:16px;color:#111827">How did we do?</p>
  <div>
    <span class="kn-fallback">
      <a href="https://mailinapp.com/v/eyJhbGci.../act?blockId=rating-1&blockType=rating&action=rate&rating=5"
         style="display:inline-block;margin:0 6px 6px 0;padding:8px 14px;border:1px solid #d1d5db;border-radius:6px;background-color:#ffffff;color:#111827;font-size:14px;text-decoration:none">
        5★
      </a>
    </span>
  </div>
</div>

This is the tier-2 link for one star chip — visible only where the equivalent in-email <form> is CSS-hidden — pointing at /v/[token]/act with the score carried as a query parameter.

Related