List Subscribers - Sequenzy

GET

api

subscribers

List Subscribers

curl --request GET \
  --url https://api.sequenzy.com/api/v1/subscribers \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.sequenzy.com/api/v1/subscribers', 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/subscribers",
  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/subscribers"

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

}

require 'uri'
require 'net/http'

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

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,
  "subscribers": [
    {
      "id": "sub_abc123",
      "email": "user@sequenzy.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "unsubscribedAt": null,
      "emailProvider": "gmail",
      "tags": ["customer", "newsletter"],
      "customAttributes": { "plan": "pro" },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1000,
    "total": 150,
    "totalPages": 1,
    "nextCursor": null,
    "hasMore": false,
    "orderBy": "created_at_desc_id_desc"
  }
}

{
  "success": true,
  "subscribers": [
    {
      "id": "sub_abc123",
      "email": "user@sequenzy.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "emailProvider": "gmail",
      "tags": ["customer", "newsletter"],
      "customAttributes": { "mrr": 99 },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": null,
    "totalPages": null,
    "nextCursor": "NEXT_CURSOR",
    "hasMore": true,
    "orderBy": "subscriber_id_asc"
  }
}

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "status must be one of active, unsubscribed, bounced, or all"
}

{
  "success": false,
  "error": "Attribute filters must include a value after \"attributeName:\"."
}

{
  "success": false,
  "error": "cursor cannot be combined with page. Keep following nextCursor instead of incrementing page."
}

{
  "success": false,
  "error": "Segment not found"
}

{
  "success": false,
  "error": "List not found"
}

{
  "success": false,
  "error": "Internal server error"
}

List subscribers with stable pagination and optional filtering by status, free-text query, tags, list, segment, attribute, email, or opt-out date. Each subscriber carries unsubscribedAt, the date the contact opted out. Use it rather than updatedAt to date an opt-out - updatedAt moves on any later tag or attribute write. It is null unless the contact is currently unsubscribed, so a contact who left one list but still receives email does not carry a date, and it is null for contacts imported as already unsubscribed, where no opt-out date exists. Without an attribute filter, results are ordered by createdAt descending, with subscriber ID used as a tie-breaker so page boundaries stay deterministic when multiple subscribers have the same creation time. With an attribute filter, results use ClickHouse-first cursor pagination and are ordered by subscriber ID ascending. Attribute-filtered responses do not include a total count; use pagination.nextCursor until it is null.

Pulling a full audience

Every response includes pagination.nextCursor and pagination.hasMore. When you need more than one page - a backup, an export, a migration - follow nextCursor instead of incrementing page:

Page numbers are computed with an offset, so rows can be skipped or repeated if subscribers are created or deleted while you are paging. A cursor walks a fixed sort key and is not affected.
Cursor requests skip the total-count query, so total and totalPages come back as null. Read the count from your first (cursorless) request.
With limit=1000, a 10,000-subscriber audience takes ten requests.

# First request: no cursor, returns the total
curl "https://api.sequenzy.com/api/v1/subscribers?status=active&limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Then follow nextCursor until hasMore is false
curl "https://api.sequenzy.com/api/v1/subscribers?status=active&limit=1000&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_API_KEY"

Searching for one address

A query that is a whole email address is treated as an identity lookup: it matches contacts whose email is that address (case-insensitively), or whose external ID is that address, and nothing else. Anything shorter - gmail.com, @example.com, ana - stays a substring search across email, external ID, first name, last name, and tags. The distinction matters on a large audience. A substring search has to examine every contact you have; an address lookup does not. If you only need one contact and you already know the address, prefer GET /v1/subscribers/{email}, which returns the full contact record directly.

Query Parameters

number

default:"1"

Page number. Cannot be combined with cursor.

number

default:"20"

Items per page (max 1000)

string

Cursor returned as pagination.nextCursor. Cannot be combined with page. Attribute-filtered requests return their own cursor, which is not interchangeable with the default-ordering cursor.

string

Pass false to skip the total-count query on page-numbered requests. Cursor requests always skip it.

string

Filter by status: active, unsubscribed, bounced, or all. Use all to disable status filtering.

string

Free-text search across email, first name, last name, and tags. A term that is a whole email address is matched exactly against the contact’s email or external ID instead - see Searching for one address.

string

Legacy alias for query. Follows the same matching rules.

string

Comma-separated tag names. A subscriber must have all provided tags.

string

Filter by a custom attribute using attributeName:value syntax, such as plan:pro or mrr:50. Use attributeName: only with empty-check operators.

string

default:"is"

Attribute operator. Direct cursor pagination supports inclusion operators: is, contains, gt, gte, lt, lte, and is_not_empty. For exclusion operators such as is_not, not_contains, or is_empty, create a saved segment and pass segmentId.

string

Subscriber list ID or exact list name. The API tries ID first, then exact name.

string

Filter by subscriber list ID.

string

Filter by exact subscriber list name when the ID is not known.

string

Filter by an existing segment ID

string

Only return contacts whose unsubscribedAt is on or after this ISO 8601 date or datetime. Bare dates use UTC midnight; datetimes must include Z or an explicit offset. Contacts with no opt-out date are excluded, which includes active contacts and imports with no known date.

string

Only return contacts whose unsubscribedAt is on or before this ISO 8601 date or datetime. Bare dates use UTC midnight; datetimes must include Z or an explicit offset.

curl "https://api.sequenzy.com/api/v1/subscribers?page=1&limit=100&status=active&list=Master%20List" \
  -H "Authorization: Bearer YOUR_API_KEY"

Reconcile a window of opt-outs against another system:

curl "https://api.sequenzy.com/api/v1/subscribers?status=unsubscribed&unsubscribedAfter=2026-07-01&unsubscribedBefore=2026-08-01&limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.sequenzy.com/api/v1/subscribers?attribute=mrr%3A50&attributeOperator=gte" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.sequenzy.com/api/v1/subscribers?attribute=mrr%3A50&attributeOperator=gte&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

{
  "success": true,
  "subscribers": [
    {
      "id": "sub_abc123",
      "email": "user@sequenzy.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "unsubscribedAt": null,
      "emailProvider": "gmail",
      "tags": ["customer", "newsletter"],
      "customAttributes": { "plan": "pro" },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1000,
    "total": 150,
    "totalPages": 1,
    "nextCursor": null,
    "hasMore": false,
    "orderBy": "created_at_desc_id_desc"
  }
}

{
  "success": true,
  "subscribers": [
    {
      "id": "sub_abc123",
      "email": "user@sequenzy.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "emailProvider": "gmail",
      "tags": ["customer", "newsletter"],
      "customAttributes": { "mrr": 99 },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": null,
    "totalPages": null,
    "nextCursor": "NEXT_CURSOR",
    "hasMore": true,
    "orderBy": "subscriber_id_asc"
  }
}

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "status must be one of active, unsubscribed, bounced, or all"
}

{
  "success": false,
  "error": "Attribute filters must include a value after \"attributeName:\"."
}

{
  "success": false,
  "error": "cursor cannot be combined with page. Keep following nextCursor instead of incrementing page."
}

{
  "success": false,
  "error": "Segment not found"
}

{
  "success": false,
  "error": "List not found"
}

{
  "success": false,
  "error": "Internal server error"
}

List Subscribers

curl --request GET \
  --url https://api.sequenzy.com/api/v1/subscribers \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.sequenzy.com/api/v1/subscribers', 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/subscribers",
  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/subscribers"

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

}

require 'uri'
require 'net/http'

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

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,
  "subscribers": [
    {
      "id": "sub_abc123",
      "email": "user@sequenzy.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "unsubscribedAt": null,
      "emailProvider": "gmail",
      "tags": ["customer", "newsletter"],
      "customAttributes": { "plan": "pro" },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1000,
    "total": 150,
    "totalPages": 1,
    "nextCursor": null,
    "hasMore": false,
    "orderBy": "created_at_desc_id_desc"
  }
}

{
  "success": true,
  "subscribers": [
    {
      "id": "sub_abc123",
      "email": "user@sequenzy.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "emailProvider": "gmail",
      "tags": ["customer", "newsletter"],
      "customAttributes": { "mrr": 99 },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": null,
    "totalPages": null,
    "nextCursor": "NEXT_CURSOR",
    "hasMore": true,
    "orderBy": "subscriber_id_asc"
  }
}

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "status must be one of active, unsubscribed, bounced, or all"
}

{
  "success": false,
  "error": "Attribute filters must include a value after \"attributeName:\"."
}

{
  "success": false,
  "error": "cursor cannot be combined with page. Keep following nextCursor instead of incrementing page."
}

{
  "success": false,
  "error": "Segment not found"
}

{
  "success": false,
  "error": "List not found"
}

{
  "success": false,
  "error": "Internal server error"
}

​Pulling a full audience

​Searching for one address

​Query Parameters

​Responses

Pulling a full audience

Searching for one address

Query Parameters

Responses