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

> ## Agent Instructions
> Usertick runs surveys on websites, by link, by QR code and by email, and collects every response in one inbox with reports, dashboards and workflows. The REST API lives at https://app.usertick.com/api/public/v1 and uses Bearer API keys or OAuth access tokens; the JavaScript SDK is the @usertick/snippet package on npm.

# Email sends

> Read your survey email sends through the Usertick REST API: who each send reached, what happened to each message and how many recipients each status counts.

The email sends endpoints read the sends in **Email**: which survey went out, to whom, when, and what happened to each message. These endpoints only read, so sending, scheduling, canceling and test emails stay in Usertick.

| Endpoint | Scopes | Does |
| - | - | - |
| [`GET /email/sends`](https://docs.usertick.com/developers/api/reference/list-email-sends) | `email:read` | Lists the sends of one view |
| [`GET /email/sends/{sendId}`](https://docs.usertick.com/developers/api/reference/get-email-send) | `email:read` | Returns one send, its answered count counted now |
| [`GET /email/sends/{sendId}/recipients`](https://docs.usertick.com/developers/api/reference/list-email-send-recipients) | `email:read`, `contacts:read` | Lists a send's recipients with their addresses |
| [`GET /email/sends/{sendId}/recipients/summary`](https://docs.usertick.com/developers/api/reference/get-email-send-recipient-summary) | `email:read` | Counts a send's recipients by status |

Because the recipient list holds addresses, it also requires `contacts:read`. An app or an AI assistant acts as the person who connected it and, with the **View surveys and results** permission, reads the sends of the surveys that person's role reaches. An API key reads every send of the organization.

## List sends

`GET /email/sends` takes a `view`:

* `past` (the default) lists every send that isn't waiting for a later time, newest first.
* `scheduled` lists the sends that wait for their time, soonest first.
* `attention` lists the sends that failed or stopped in the last 30 days.

`surveyId` keeps one survey's sends, and `search` matches part of the subject, the survey's name or a list's name, up to 200 characters. `sort` takes `when`, `survey`, `recipients` or `answered`, with `:asc` or `:desc`, such as `recipients:desc`. Because scheduled sends haven't gone out, the `scheduled` view doesn't offer `answered` as a sort.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "99999999-9999-4999-8999-999999999999",
  "surveyId": "11111111-1111-4111-8111-111111111111",
  "surveyName": "Onboarding NPS",
  "subject": "How are we doing?",
  "status": "sent",
  "locale": "en",
  "recipientCount": 240,
  "sentCount": 236,
  "failedCount": 1,
  "skippedCount": 3,
  "answeredCount": 58,
  "answeredCountedAt": "2026-10-02T09:00:00.000Z",
  "bouncedCount": 2,
  "complainedCount": 0,
  "viaUsertick": true,
  "stopReason": null,
  "scheduledAt": null,
  "completedAt": "2026-10-01T09:04:00.000Z",
  "createdAt": "2026-10-01T09:00:00.000Z",
  "sendAt": "2026-10-01T09:00:00.000Z",
  "audience": { "allContacts": false, "lists": [{ "id": "88888888-8888-4888-8888-888888888888", "name": "Beta testers" }], "people": 0, "contactIds": null }
}
```

| Field | Meaning |
| - | - |
| `status` | `queued`, `sending`, `sent`, `failed` or `canceled`. A scheduled send is `queued` until its time. |
| `answeredCount` | How many people answered through the send's links, `null` before the send went out. In the list it is the last stored count, and `answeredCountedAt` says when it was counted; `GET /email/sends/{sendId}` counts it now. |
| `viaUsertick` | The send went out through Usertick, so it counts toward your plan's emails. |
| `stopReason` | Why a send stopped before reaching everyone: `quota`, `paused`, `list_deleted` or `survey_closed`. |
| `audience` | Who the send was for: everyone in Contacts, its lists by their names at the time, and how many hand-picked `people`. |

`audience.contactIds` is `null` in the list. `GET /email/sends/{sendId}` fills it with the hand-picked people who are still contacts, by ID only, and [`GET /contacts/{contactId}`](https://docs.usertick.com/developers/api/reference/get-contact) reads their addresses with `contacts:read`.

## Read who a send reached

`GET /email/sends/{sendId}/recipients` lists each recipient, oldest first:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    { "contactId": "77777777-7777-4777-8777-777777777777", "email": "maya@example.com", "status": "sent", "error": null, "createdAt": "2026-10-01T09:00:02.000Z" },
    { "contactId": null, "email": null, "status": "bounced", "error": "Mailbox unavailable", "createdAt": "2026-10-01T09:00:03.000Z" }
  ],
  "nextCursor": null
}
```

* `status` is `sent`, `failed`, `bounced`, `complained`, or a skipped reason: `skipped_unsubscribed`, `skipped_dedup` (the person had this survey before), `skipped_suppressed`, `skipped_quota`, `skipped_paused` or `skipped_survey_closed`.
* The `status` filter takes `all`, `sent`, `failed`, `bounced`, `complained` or `skipped`, which keeps every skipped reason.
* `search` matches part of the address, and `sort` takes `time`, `email` or `status`, with `:asc` or `:desc`.
* `email` is `null` once the contact was deleted or erased, because Usertick blanks the address in the send history and keeps the row so the send's counts stay.

`GET /email/sends/{sendId}/recipients/summary` counts every recipient of the send by status, without addresses, and groups the failed ones by error text. It returns the 50 most common texts, with `failureReasonTotal` giving how many different texts there are.

## Errors

A send that isn't your organization's, or whose survey your role doesn't reach, returns `404` with `PUB-014-001`. A `surveyId` that isn't one of your surveys returns `404` with `APK-006-005`. A sort, a view or a filter value the list doesn't take returns `400` with `PUB-001-004` for that parameter. See [Errors](https://docs.usertick.com/developers/api/errors.md#email-sends).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.