> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Polls & NPS Surveys

> Collect one-click feedback in your emails and use it for segmentation and automation

# Polls & NPS Surveys

The poll block lets recipients answer a question with a single click, directly from their inbox. Every answer is saved to a subscriber attribute and fires a `poll.answered` event, so the feedback feeds straight into your segments, sync rules, and automated sequences.

## How It Works

Each answer in the block is a regular link, so polls work in every email client with no JavaScript or forms. When a recipient clicks an answer:

1. Sequenzy records the answer on their subscriber profile, in the attribute you chose (for example `email_feedback` or `nps_score`).
2. A `poll.answered` event is recorded with the question, the answer, and the email that asked it.
3. The recipient lands on a hosted thank-you page (or a page of your choosing).

Answers also count as clicks for engagement stats. Clicks from security scanners and link-preview bots are filtered out so they cannot fabricate answers, every answer link is cryptographically signed so its payload cannot be tampered with, and re-clicking the same answer is a no-op. If someone changes their answer, the latest answer wins.

## Adding a Poll

1. While editing a campaign or automation email, open the block menu or type `/poll` (or `/nps`)
2. Insert the **Poll** block for answer buttons, or the **NPS Survey** block for a 0-10 scale
3. Click the question or any answer to edit the copy inline, and open the block settings for everything else

## Settings

* **Type**: Answers shows one button per option; NPS 0-10 shows a numeric scale with captions under each end.
* **Question**: the prompt shown above the answers.
* **Answers**: add up to 8 options (2 minimum), drag to reorder. Emoji work well, for example "😍 Loved it". Under **Stored values** you can give each answer a stable stored value (for example `loved`) so segments keep working when you reword a label.
* **Language**: the hosted thank-you page follows your company's email language automatically.
* **Save answer to attribute**: the subscriber attribute that stores the latest answer. NPS scores are stored as numbers, so segments can filter with ranges like `nps_score ≤ 6`. Reuse the same attribute across sends when you want one always-current value, or use a different attribute per campaign to keep answers separate.
* **After voting**: customize the thank-you message on the hosted confirmation page, or redirect respondents to your own URL instead. The settings panel shows a live preview of the hosted page as you type.
* **Style**: pick how the answers look. **Soft** (lightly tinted, the default), **Pill** (borderless rounded chips), **Outline** (white with an accent border), and **Filled** (solid accent color) are button styles; **Pop** adds a bold ink border with a hard accent shadow, **Brutal** goes full poster - square corners, heavy ink border and shadow, uppercase answers - **Quiz** puts an A/B/C letter badge in front of each left-aligned answer, and **Minimal** drops the boxes entirely for a ruled list with an accent arrow (NPS scores sit on an accent underline). The style picker previews each option in your accent color.
* **Accent color**: override the brand primary color for the answer buttons.

## Results

Once responses arrive, the campaign's stats view shows a **Poll Results** card: the answer distribution for each poll, and for NPS surveys the score itself (% promoters - % detractors) with the promoter / passive / detractor split and the full 0-10 distribution. Each subscriber counts once per poll, using their latest answer.

To see who is behind a count, click an answer row - or the promoter / passive / detractor counts on an NPS survey. This opens the subscribers page pre-filtered by the exact historical response for that campaign and poll block, so it remains accurate even if a later poll overwrites the subscriber's current attribute. From there you can browse the respondents, save them as a segment, or start a targeted campaign.

The same summary is returned by the campaign metrics API (`GET /api/v1/metrics/campaigns/{id}`) as a `polls` array, and by the `get_campaign_stats` MCP tool and `sequenzy stats --campaign`. Each summary includes the poll `blockId`, the `attributeKey` where the current/latest response is stored, and each option's stable `value`. For an exact historical drill-down, create a segment with field `pollResponse`, operator `is`, and a campaign-and-block-scoped JSON value. The older `GET /api/v1/campaigns/{id}/stats` route remains a compatibility alias.

## API, CLI, and MCP

Polls are native email blocks, so the same block JSON works in campaigns, templates, A/B variants, transactional templates, and sequence email steps. An answer-button poll looks like this:

Transactional poll sends must resolve to exactly one effective recipient after suppression filtering and recipient deduplication, and that recipient must already exist as a subscriber. Sequenzy rejects the send otherwise because each answer link must be attributable to one subscriber.

```json theme={null}
{
  "type": "poll",
  "variant": "options",
  "question": "What did you think of this email?",
  "options": [
    { "label": "Loved it", "value": "loved" },
    { "label": "It was okay", "value": "okay" },
    { "label": "Not for me", "value": "not_for_me" }
  ],
  "attributeKey": "email_feedback",
  "confirmationMessage": "Thanks for the feedback!"
}
```

The optional `appearance` field picks the answer style: `"soft"` (default), `"pill"`, `"outline"`, `"filled"`, `"pop"`, `"brutal"`, `"quiz"`, or `"minimal"`.

For NPS, use `variant: "nps"`; the scale is always 0-10 and `options` is empty:

```json theme={null}
{
  "type": "poll",
  "variant": "nps",
  "question": "How likely are you to recommend us?",
  "options": [],
  "attributeKey": "nps_score",
  "npsLowLabel": "Not likely",
  "npsHighLabel": "Very likely"
}
```

With the CLI, include either block in the email's block array and pass the file through an existing content command:

```bash theme={null}
sequenzy campaigns create "Customer pulse" \
  --subject "One quick question" \
  --blocks-file ./customer-pulse-blocks.json

sequenzy stats --campaign camp_abc123
sequenzy stats --campaign camp_abc123 --json
```

With MCP, pass the same array as `blocks` to tools such as `create_campaign`, `update_campaign`, `create_template`, or a sequence email step. Read response distributions with `get_campaign_stats`; its top-level `polls` array includes NPS score, average, and promoter/passive/detractor counts when applicable. To create a segment containing the exact respondents behind a count, use a `pollResponse` value with the campaign ID and the summary's `blockId`.

For an options answer:

```json theme={null}
{
  "v": 1,
  "campaignId": "camp_abc123",
  "blockId": "poll_1",
  "match": { "kind": "answer", "value": "loved" }
}
```

For an NPS bucket:

```json theme={null}
{
  "v": 1,
  "campaignId": "camp_abc123",
  "blockId": "poll_nps",
  "match": { "kind": "npsBucket", "bucket": "detractors" }
}
```

NPS buckets are `promoters`, `passives`, or `detractors`.

## Using the Responses

* **Segments**: filter on the poll attribute when you want the subscriber's current/latest answer, for example `nps_score` less than or equal to 6. Use the campaign-and-block-scoped `pollResponse` filter above when you need the exact historical respondents to one poll.
* **Sequences**: use the **Event Received** trigger with the `poll.answered` event to follow up automatically, for example asking detractors what went wrong or inviting promoters to leave a review.
* **Sync rules**: map `poll.answered` events to tags to keep long-lived labels like `nps-promoter` in sync.
* **Webhooks**: subscribe an [outbound webhook](/integrations/outbound-webhooks) to `poll.answered` to push each answer into your own systems.
* **Subscriber profile**: each response also appears in the subscriber's activity feed.

## Good To Know

* Polls need a delivered Sequenzy email to record answers - clicks in the editor preview open an explanatory page instead, and test-email votes show the thank-you page without recording anything.
* One question per email works best. If you need multiple questions, link out to a full survey instead.
* The block looks identical in the editor, the preview, and the sent email.