Get List

Retrieve a specific list by UUID, including its contact count and, on request, a mailability breakdown of its members.

Request

GET /lists/{uuid}

Path Parameters

Parameter	Type	Description
uuid	string	List's UUID

Query Parameters

All parameters are optional.

Parameter	Type	Default	Description
include	string	-	Comma-separated list of extra sections to add to the response. Currently stats is the only supported section. Unrecognised values are ignored.

Each section you name is added as an extra key on data. A section you don't request is omitted entirely — it is not returned as null — so the default response is unchanged. See Stats Object.

Example Requests

Retrieve a list:

curl -X GET "https://email.easy.tools/api/v1/lists/70dbd819-fac2-4dcf-b655-fb925e24410b" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Retrieve a list with the mailability breakdown of its members:

curl -X GET "https://email.easy.tools/api/v1/lists/70dbd819-fac2-4dcf-b655-fb925e24410b?include=stats" \
  -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": 1500,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

When include names stats, a stats object is added to data:

{
  "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": 1500,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "stats": {
      "subscribed": 1320,
      "unsubscribed": 140,
      "suppressed": 55
    }
  }
}

Response Fields

The list has the fields described in List Object, plus a stats object when include names stats — see Stats Object.

Stats Object

Present only when stats is named in include. A breakdown of the list's members by whether they can be mailed:

Field	Type	Description
subscribed	integer	Members who will receive mail — neither unsubscribed nor suppressed at the account level. This is the list's mailable size.
unsubscribed	integer	Members who have opted out of all mail at the account level.
suppressed	integer	Members whose address is undeliverable (for example, after a permanent bounce) and held back from sending.

These three counts are not mutually exclusive. A member can be counted in both unsubscribed and suppressed, so those two sets may overlap. subscribed is the exact complement of "unsubscribed or suppressed". Because of the overlap, do not add the three together for a total — use contacts_count for the raw member count.

Error Responses

Not Found Error (404)

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "List with uuid '70dbd819-fac2-4dcf-b655-fb925e24410b' not found"
  }
}