List contacts

GET /api/v1/contacts Contacts of one list, paginated. listId is required: a read is always scoped to one list, there is no organization-wide contact listing. A request without it answers 400. Get your list ids from GET /api/v1/lists — see Discovery. tagId takes the id of a tag, not its name: call GET /api/v1/tags first and pick the id of the tag whose name you are after.
The organization is never a parameter. It comes from the key. An organizationId passed in the query is ignored — you can only ever read your own audience. A listId belonging to another organization answers 404, not an empty page.
Every contact in the response carries exactly these fields: id, email, firstName, lastName, status, listId, list, tags and its createdAt / updatedAt dates. Nothing else — in particular, the unsubscribe token of a contact is never exposed by this API.

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
listIdstringList to read. Contacts are always scoped to a list.
statusstringpending, subscribed, unsubscribed, bounced, complained
tagIdstringOnly contacts carrying this tag — a tag id, not a name
searchstringMatches email, first name or last 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/contacts?listId=$LIST_ID&status=subscribed&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 contact
data[].emailstringIts address — unique inside its list
data[].firstNamestringnull
data[].lastNamestringnull
data[].statusstringpending, subscribed, unsubscribed, bounced, complained
data[].listIdstringThe list it belongs to
data[].listobject{id, name} of that list
data[].tagsarray{id, name} of every tag carried
data[].createdAtstringISO creation date
data[].updatedAtstringISO date of the last change
paginationobject{total, page, limit, totalPages}

Example response

json
{
  "success": true,
  "data": [
    {
      "id": "4d19c0a2",
      "email": "ada@example.com",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "status": "subscribed",
      "listId": "0b7c51e8",
      "list": {
        "id": "0b7c51e8",
        "name": "Newsletter"
      },
      "tags": [
        {
          "id": "7c2ef4b1",
          "name": "vip"
        }
      ],
      "createdAt": "2026-08-23T10:22:05.000Z",
      "updatedAt": "2026-08-23T10:22:05.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Related