List Segment Contacts

Retrieve a paginated list of the contacts who currently match a segment and can receive mail.

Unsubscribed and undeliverable contacts are excluded. See Subscription status. Who matches is the segment's filters.

Request

GET /segments/{uuid}/contacts

Path Parameters

Parameter	Type	Description
uuid	string	Segment's UUID

Query Parameters

All parameters are optional.

Parameter	Type	Default	Description
page	integer	1	Page number (min: 1)
per_page	integer	100	Items per page (min: 1, max: 100)
search	string	—	Partial match on the contact's name, email, or phone (max 255 characters)

Ordering: Results are ordered by created_at descending (newest first).

An out-of-range page or per_page, or a search value over the length limit, returns 422 VALIDATION_ERROR.

Example Request

curl -X GET "https://email.easy.tools/api/v1/segments/60707a92-80d0-468e-8a13-38b90c0511db/contacts?page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

Success Response (200 OK)

Each item has the same shape as a List Contacts item.

{
  "data": [
    {
      "uuid": "0a0d4ecd-1a3e-4a47-96b5-c57c05567f92",
      "email": "buyer@example.com",
      "first_name": "Alex",
      "last_name": "Kim",
      "phone": "+12025550148",
      "external_id": null,
      "language": "en",
      "country_code": "US",
      "created_at": "2026-04-12T15:22:08Z",
      "updated_at": "2026-06-03T11:18:44Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 1284
  }
}

Response Fields

Each item is identical to a List Contacts item; see that page for the full field reference.

Pagination Object

Field	Type	Description
current_page	integer	Current page number
per_page	integer	Number of items per page
total	integer	Number of contacts who match this request

pagination.total is counted from the segment's filters and search, and can be up to about a minute old. It can differ from the segment's cached contacts_count — see Audience size. To read only the count, request per_page=1 and use pagination.total.

Error Responses

Not Found Error (404)

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Segment with UUID '60707a92-80d0-468e-8a13-38b90c0511db' not found"
  }
}

Validation Error (422 Unprocessable Entity)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "per_page": ["The per page field must not be greater than 100."]
    }
  }
}

Validation Error (422 — Filters Unresolved)

The segment's audience cannot be resolved from its stored filters. When the filters reference a custom field that no longer exists, details.unresolved_field_keys lists those field keys.

{
  "error": {
    "code": "SEGMENT_FILTERS_UNRESOLVED",
    "message": "The segment audience cannot be resolved because its filters reference custom fields that no longer exist",
    "details": {
      "unresolved_field_keys": ["as:one_time_product"]
    }
  }
}

When the stored filters are no longer valid, details.unresolved_field_keys is empty.

{
  "error": {
    "code": "SEGMENT_FILTERS_UNRESOLVED",
    "message": "The segment audience cannot be resolved because its filters are no longer valid",
    "details": {
      "unresolved_field_keys": []
    }
  }
}

Service Unavailable Error (503)

The matching contacts could not be counted or loaded in time, so no page is returned. When the count timed out, it is not attempted again for the same segment and search for about a minute — retry after that. A page that timed out is loaded again on the next request.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The request could not be completed. Try again shortly."
  }
}