Messaging · iMessage

List iMessage audience

Returns iMessage audience, one page at a time.

GEThttps://api.pozy.ai/v1/imessage/audience

listImessageAudience

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys can call it. Authentication

Query parameters

Name	Type	Notes
`accountId`	string
`status`	string	One of `subscribed`, `unsubscribed`
`search`	string	Up to 120 characters
`limit`	integer	Default `50`1 to 200
`skip`	integer	Default `0`At least 0

Example

curl -X GET "https://api.pozy.ai/v1/imessage/audience?limit=50" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/imessage/audience?limit=50", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);

import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/imessage/audience",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "limit": 50,
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

200 on success

contactsarray of object
9 child fields
- conversationIdstring
- accountIdstring
- contactstring
- namestring
  Can be null.
- subscribedboolean
- lastMessagestring
  Can be null.
- lastMessageAtstring (date-time)
  Can be null.
- firstSeenAtstring (date-time)
  Can be null.
- optInobject
  Can be null.
  2 child fields
  atstring (date-time)
  parametersobject
totalinteger
limitinteger
skipinteger

200 response

{
  "contacts": [
    {
      "conversationId": "6e525f3820fc636aa96d2ee9",
      "accountId": "696e0b682d0a31188e7a2ba9",
      "contact": "string",
      "name": "Acme",
      "subscribed": true,
      "lastMessage": "Hello from Pozy",
      "lastMessageAt": "2026-10-02T09:00:00.000Z",
      "firstSeenAt": "2026-10-02T09:00:00.000Z",
      "optIn": {
        "at": "2026-10-02T09:00:00.000Z",
        "parameters": {}
      }
    }
  ],
  "total": 42,
  "limit": 1,
  "skip": 1
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400	invalid_request_error	A parameter or body field is missing or invalid. `param` names it.
401	authentication_error	The API key is missing, revoked or expired.
403	permission_error	The key is scoped to other profiles or has this resource group disabled.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.

More in iMessage

GETList iMessage senders POSTRegister an iMessage sender GETList iMessage sender orders POSTOrder a new iMessage sender GETGet iMessage sender status PATCHUpdate an iMessage sender DELCancel an iMessage sender GETList iMessage sandbox contacts POSTAdd an iMessage sandbox contact DELRemove an iMessage sandbox contact POSTSubscribe or opt out an iMessage contact POSTCreate a tracked iMessage opt-in link GETList instantly available iMessage numbers POSTReserve an available iMessage number POSTStart an iMessage group chat GETGet an iMessage group PATCHRename an iMessage group or change its photo POSTAdd a participant to an iMessage group DELRemove a participant from an iMessage group