Skip to main content
GET
/
api
/
v1
/
metrics
/
recipients
Get Recipient Metrics
curl --request GET \
  --url https://api.sequenzy.com/api/v1/metrics/recipients \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://api.sequenzy.com/api/v1/metrics/recipients"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.sequenzy.com/api/v1/metrics/recipients', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sequenzy.com/api/v1/metrics/recipients",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.sequenzy.com/api/v1/metrics/recipients"

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("Authorization", "Bearer <token>")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.sequenzy.com/api/v1/metrics/recipients")
.header("Authorization", "Bearer <token>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/metrics/recipients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
{
  "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
  }
}
{ "success": false, "error": "Cannot filter by both campaignId and sequenceId" }
{ "success": false, "error": "Unauthorized" }
{ "success": false, "error": "Campaign not found" }
{ "success": false, "error": "Internal server error" }
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

email
string
Filter to a single recipient by email address.
campaignId
string
Filter to recipients of a specific campaign. Cannot be combined with sequenceId.
sequenceId
string
Filter to recipients of a specific sequence. Cannot be combined with campaignId.
period
string
Sliding time window. One of: 1h, 24h, 7d, 30d, 90d. Ignored when start and end are provided.
start
string
Start of custom time range (ISO 8601). Must be used with end.
end
string
End of custom time range (ISO 8601). Must be used with start. Max range: 90 days.
page
number
default:"1"
Page number for pagination.
limit
number
default:"20"
Recipients per page (max 100).
includeMachineEngagement
boolean
default:"false"
Set to true to include detected scanner, preview, and tracked asset open/click events in each recipient’s engagement arrays.

Response Fields

FieldTypeDescription
recipients[].emailstringRecipient email address
recipients[].openedarrayList of open events with campaignId, subject, and at timestamp
recipients[].opened[].machinebooleanWhether the event is classified as bot/scanner activity
recipients[].opened[].engagementQualitystringhuman, machine, or asset
recipients[].opened[].classificationReasonsarrayClassification reason codes, such as microsoft_office_scanner, managed_image_asset, or static_brand_asset
recipients[].clickedarrayList of click events with campaignId, subject, url, and at timestamp
recipients[].clicked[].machinebooleanWhether the event is classified as bot/scanner activity
recipients[].clicked[].engagementQualitystringhuman, machine, or asset
recipients[].clicked[].classificationReasonsarrayClassification reason codes, such as microsoft_office_scanner, managed_image_asset, or static_brand_asset
recipients[].unsubscribedbooleanWhether the recipient unsubscribed
pagination.pagenumberCurrent page
pagination.limitnumberResults per page
pagination.totalnumberTotal matching recipients
pagination.totalPagesnumberTotal pages available

Common Queries

How did a specific user interact with our emails?

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?

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

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:
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

{
  "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
  }
}
{ "success": false, "error": "Cannot filter by both campaignId and sequenceId" }
{ "success": false, "error": "Unauthorized" }
{ "success": false, "error": "Campaign not found" }
{ "success": false, "error": "Internal server error" }