List tags

List tags

GET /api/v1/tags Every tag of the organization, with the number of contacts carrying each one. Tags cross lists — this listing is the whole vocabulary an agent can target with.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Allowed

A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Query parameters

Parameter	Type	Description
`search`	string	Filters on the name, case-insensitive. Optional
`page`	number	Page number, default `1`
`limit`	number	Items per page, default `20`, capped at `100`

Example

bash

curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/tags?search=vip"

Response

200 OK — the tags, with a pagination object next to them.
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

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`data`	array	The tags
`data[].id`	string	Unique identifier for the tag
`data[].name`	string	Name of the tag, unique in the organization
`data[].contactCount`	number	Contacts carrying it — on this listing only
`data[].createdAt`	string	ISO creation date
`data[].updatedAt`	string	ISO date of the last change
`pagination`	object	`{total, page, limit, totalPages}`

Example response

json

{
  "success": true,
  "data": [
    {
      "id": "7c2e…",
      "name": "vip",
      "contactCount": 128,
      "createdAt": "2026-03-04T08:11:00.000Z",
      "updatedAt": "2026-08-01T10:42:19.000Z"
    }
  ],
  "pagination": {"total": 1, "page": 1, "limit": 20, "totalPages": 1}
}

Notes

contactCount exists on this listing only. Creating a tag or attaching one answers without it — counting on every write would cost a query nobody asked for.
Renaming a tag is safe everywhere: targeting follows the tag, not its name.