> ## 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.

# Get Recipient Metrics

> Retrieve paginated recipient engagement data including opens, clicks, and unsubscribes.

Returns a paginated list of recipients who received emails, along with their engagement events (opens, clicks, unsubscribes). Use this endpoint to sync engagement data to your own database or to look up how a specific person interacted with your emails. Test sends are excluded from recipient engagement results by default so previews do not skew results, but they still count toward send usage and quota. Open and click events also exclude detected email-security scanners and tracked brand assets by default.

## Query Parameters

<ParamField query="email" type="string">
  Filter to a single recipient by email address.
</ParamField>

<ParamField query="campaignId" type="string">
  Filter to recipients of a specific campaign. Cannot be combined with
  `sequenceId`.
</ParamField>

<ParamField query="sequenceId" type="string">
  Filter to recipients of a specific sequence. Cannot be combined with
  `campaignId`.
</ParamField>

<ParamField query="period" type="string">
  Sliding time window. One of: `1h`, `24h`, `7d`, `30d`, `90d`. Ignored when
  `start` and `end` are provided.
</ParamField>

<ParamField query="start" type="string">
  Start of custom time range (ISO 8601). Must be used with `end`.
</ParamField>

<ParamField query="end" type="string">
  End of custom time range (ISO 8601). Must be used with `start`. Max range: 90
  days.
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Recipients per page (max 100).
</ParamField>

<ParamField query="includeMachineEngagement" type="boolean" default="false">
  Set to `true` to include detected scanner, preview, and tracked asset
  open/click events in each recipient's engagement arrays.
</ParamField>

## Response Fields

| Field                                          | Type      | Description                                                                                                     |
| ---------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- |
| `recipients[].email`                           | `string`  | Recipient email address                                                                                         |
| `recipients[].opened`                          | `array`   | List of open events with `campaignId`, `subject`, and `at` timestamp                                            |
| `recipients[].opened[].machine`                | `boolean` | Whether the event is classified as bot/scanner activity                                                         |
| `recipients[].opened[].engagementQuality`      | `string`  | `human`, `machine`, or `asset`                                                                                  |
| `recipients[].opened[].classificationReasons`  | `array`   | Classification reason codes, such as `microsoft_office_scanner`, `managed_image_asset`, or `static_brand_asset` |
| `recipients[].clicked`                         | `array`   | List of click events with `campaignId`, `subject`, `url`, and `at` timestamp                                    |
| `recipients[].clicked[].machine`               | `boolean` | Whether the event is classified as bot/scanner activity                                                         |
| `recipients[].clicked[].engagementQuality`     | `string`  | `human`, `machine`, or `asset`                                                                                  |
| `recipients[].clicked[].classificationReasons` | `array`   | Classification reason codes, such as `microsoft_office_scanner`, `managed_image_asset`, or `static_brand_asset` |
| `recipients[].unsubscribed`                    | `boolean` | Whether the recipient unsubscribed                                                                              |
| `pagination.page`                              | `number`  | Current page                                                                                                    |
| `pagination.limit`                             | `number`  | Results per page                                                                                                |
| `pagination.total`                             | `number`  | Total matching recipients                                                                                       |
| `pagination.totalPages`                        | `number`  | Total pages available                                                                                           |

## Common Queries

### How did a specific user interact with our emails?

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/recipients?email=user@example.com" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Returns all opens, clicks, and unsubscribe status for that person. Useful for support conversations or CRM enrichment.

### Who opened our latest campaign?

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/recipients?campaignId=camp_abc123&limit=100" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Page through the results to get all recipients. Check each recipient's `opened` array — those with entries opened the campaign.

### Who clicked a link in our onboarding sequence?

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/recipients?sequenceId=seq_abc123&limit=100" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Check each recipient's `clicked` array for entries. The `url` field shows which link they clicked.

### Who engaged in the last 24 hours?

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/recipients?period=24h&limit=50" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Sync engagement data to our database on a cron schedule

Pull yesterday's engagement data with a fixed time range:

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/recipients?start=2026-02-13T00:00:00Z&end=2026-02-14T00:00:00Z&limit=100&page=1" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Increment `page` until `page > totalPages` to get all results. Fixed time ranges are idempotent — safe to retry.

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "recipients": [
      {
        "email": "user@example.com",
        "opened": [
          {
            "campaignId": "camp_abc123",
            "subject": "February Newsletter",
            "machine": false,
            "engagementQuality": "human",
            "classificationReasons": [],
            "at": "2026-02-14T10:30:00.000Z"
          }
        ],
        "clicked": [
          {
            "campaignId": "camp_abc123",
            "subject": "February Newsletter",
            "url": "https://example.com/start",
            "machine": false,
            "engagementQuality": "human",
            "classificationReasons": [],
            "at": "2026-02-14T10:35:00.000Z"
          }
        ],
        "unsubscribed": false
      },
      {
        "email": "other@example.com",
        "opened": [],
        "clicked": [],
        "unsubscribed": true
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "totalPages": 1
    }
  }
  ```

  ```json 400 theme={null}
  { "success": false, "error": "Cannot filter by both campaignId and sequenceId" }
  ```

  ```json 401 theme={null}
  { "success": false, "error": "Unauthorized" }
  ```

  ```json 404 theme={null}
  { "success": false, "error": "Campaign not found" }
  ```

  ```json 500 theme={null}
  { "success": false, "error": "Internal server error" }
  ```
</ResponseExample>