List Contacts in List

Retrieve a paginated list of contacts that belong to a specific list.

Request

GET /lists/{listUuid}/contacts

Path Parameters

Parameter	Type	Description
listUuid	string	List's UUID

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (min: 1)
per_page	integer	100	Items per page (min: 1, max: 100)
search	string	-	If valid email: exact match. Otherwise: search by first_name, last_name, phone, or full name (max 255 characters)

Ordering: Results are ordered by added_at descending (most recently added first).

Example Request

curl -X GET "https://email.easy.tools/api/v1/lists/list-uuid-123/contacts?page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

Success Response (200 OK)

{
  "data": [
    {
      "uuid": "contact-uuid-1",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+48123456789",
      "external_id": "customer_123",
      "language": "en",
      "country_code": "US",
      "added_at": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 1
  }
}

Response Fields

Field	Type	Description
uuid	string	Contact's unique identifier
email	string	Contact's email address
first_name	string|null	Contact's first name
last_name	string|null	Contact's last name
phone	string|null	Contact's phone number
external_id	string|null	External identifier
language	string|null	ISO 639-1 language code
country_code	string|null	ISO 3166-1 alpha-2 country code
added_at	string	When the contact was added to the list (ISO 8601)
created_at	string	When the contact was created (ISO 8601)
updated_at	string	When the contact was last updated (ISO 8601)

Pagination Object

Field	Type	Description
current_page	integer	Current page number
per_page	integer	Number of items per page
total	integer	Total number of contacts in the list

Error Responses

Not Found Error (404)

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "List with uuid 'list-uuid-123' not found"
  }
}

Validation Error (422 Unprocessable Entity)

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