List Lists

Retrieve a paginated list of all contact lists with optional filtering.

Request

GET /lists

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	-	Search by list name or description (max 255 characters)

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

Example Request

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

Response

Success Response (200 OK)

{
  "data": [
    {
      "uuid": "70dbd819-fac2-4dcf-b655-fb925e24410b",
      "name": "Newsletter Subscribers",
      "description": "Main newsletter list",
      "internal_description": "Imported from the 2024 CRM export",
      "is_public": true,
      "contacts_count": 150,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    },
    {
      "uuid": "2c9a7f3e-1b8d-4e6a-bc20-5f4d3e2a1b09",
      "name": "VIP Customers",
      "description": null,
      "internal_description": null,
      "is_public": false,
      "contacts_count": 25,
      "created_at": "2025-01-14T09:00:00Z",
      "updated_at": "2025-01-14T09:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 2
  }
}

Response Fields

Each entry in data has the fields described in List Object.

contacts_count on this endpoint is approximate and may lag a list's actual membership by up to a minute. For an exact count, retrieve a single list with GET /lists/{uuid}.

Pagination Object

Field	Type	Description
current_page	integer	Current page number
per_page	integer	Number of items per page
total	integer	Total number of lists

Error Responses

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."]
    }
  }
}