List the lists

GET /api/v1/lists Lists of the organization, paginated, each with the number of contacts it holds. This is where an agent starts: almost everything else — adding a contact, importing a batch, creating a campaign — needs a listId, and this is the only way to find one you did not create yourself. Each list carries id, name, contactCount and its createdAt / updatedAt dates.

Authorization

Role in the organizationThis endpoint
OWNERAllowed
ADMINAllowed
MEMBERAllowed
A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Query parameters

ParameterTypeDescription
searchstringMatches the list name
pagenumberDefaults to 1
limitnumberDefaults to 20, capped at 100

Example

bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/lists?limit=50"

Response

  • 200 OK — the call succeeded.
  • 401 Unauthorized — missing or invalid key, or its owner left the organization.
  • 429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

FieldTypeDescription
successbooleanIndicates if the operation was successful
data[].idstringUnique identifier for the list
data[].namestringName of the list
data[].contactCountnumberContacts it holds
data[].createdAtstringISO creation date
data[].updatedAtstringISO date of the last change
paginationobject{total, page, limit, totalPages}

Example response

json
{
  "success": true,
  "data": [
    {
      "id": "4d19c0a2",
      "name": "Newsletter",
      "contactCount": 128,
      "createdAt": "2026-08-23T10:22:05.000Z",
      "updatedAt": "2026-08-23T10:22:05.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Related