Read the address book

GET /api/v1/settings/identities Every sender address this organization may use, the default first — it is the one that signs campaigns, sequences and opt-in confirmations. The others are registered and ready; they send nothing until promoted.

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.

Example

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

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

data is an array of:
FieldTypeDescription
successbooleanIndicates if the operation was successful
data[].idstringIdentifier to pass as sendingIdentityId on a campaign
data[].senderEmailstringThe address itself
data[].senderNamestring \null
data[].isDefaultbooleanExactly one address carries true
data[].createdAtstringISO date the address was added
paginationobject{total, page, limit, totalPages}

Example response

json
{
  "success": true,
  "data": [
    {"id": "8f1c…", "senderEmail": "hello@mail.example.com", "senderName": "Example", "isDefault": true, "createdAt": "2026-05-02T09:12:44.000Z"},
    {"id": "2ad9…", "senderEmail": "news@mail.example.com", "senderName": "Example News", "isDefault": false, "createdAt": "2026-06-18T14:03:11.000Z"}
  ]
}

Related