Get one list

GET /api/v1/lists/{listId} One list.
bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/lists/$LIST_ID"
The detail carries no contactCount: the count is computed only when listing. A list that does not exist, a list you deleted and a list belonging to another organization all answer 404 — the API never tells you an id exists when it is not yours, and a deleted list is no longer addressable.

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.

Path parameters

ParameterTypeDescription
listIdstringRequired. The list to read

Example

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

Response

  • 200 OK — the call succeeded.
  • 401 Unauthorized — missing or invalid key, or its owner left the organization.
  • 404 Not Found — no such resource, or you deleted it, or it belongs to another organization. The API never confirms that an id exists to a caller who has no right to it.
  • 429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

FieldTypeDescription
successbooleanIndicates if the operation was successful
data.idstringIdentifier of the list
data.namestringIts name
data.contactCountnumberContacts it holds
data.createdAt / updatedAtstringISO dates

Example response

json
{
  "success": true,
  "data": {
    "id": "4d19c0a2",
    "name": "Newsletter",
    "contactCount": 128,
    "createdAt` / `updatedAt": "value"
  }
}

Notes

  • Deleting a list in the interface makes it answer 404 here, immediately and for good. Nothing is erased on the reporting side: the campaigns sent to it keep their statistics and their recipients.

Related