List Messages

GET

api.ziett.co/c/v1 /messages

Retrieve a paginated history of all messages sent by your organization. This endpoint provides deep visibility into your transactional and marketing traffic, allowing you to audit delivery status, track routing logs, and filter communications across multiple variables.

For finding a single message instantly when you already have its unique tracking identifier, see Get Message.

Request

Required scope: apikey:messages:list

Query Parameters

Parameter	Type	Default	Description
`q`	`string`	—	Keyword search query. Matches partially against recipient phone numbers (`target_e164`) or exactly against the unique message UUID.
`page`	`integer`	`1`	The page index to retrieve. Minimum value is `1`.
`size`	`integer`	`30`	Number of records to return per page. Minimum is `1`, maximum allowed is `200`.
`order`	`enum`	`desc`	Sort direction for the results. Accepted values: `asc` (oldest first), `desc` (newest first).
`order_by`	`enum`	`created_at`	The model attribute used to sort results. Accepted values: `created_at`, `updated_at`.
`status`	`enum \| array`	—	Filter by specific delivery states. Accepted values: `PENDING`, `SENT`, `DELIVERED`, `FAILED`, `UNDELIVERED`. Pass multiple times to match several states (e.g., `status=SENT&status=FAILED`).
`channel_type`	`enum \| array`	—	Filter by transport medium. Accepted values: `SMS`, `WHATSAPP`. Can be passed multiple times.
`contact_id`	`uuid \| array`	—	Filter history for one or more specific contacts in your database.
`campaign_id`	`uuid \| array`	—	Filter messages generated by a specific batch campaign execution.
`sms_remitter_id`	`uuid \| array`	—	Filter by the specific approved Sender ID (Remitter UUID) used to dispatch the traffic.
`created_at__ge`	`datetime`	—	Lower bound date-time range limit in ISO 8601 format (inclusive). Example: `2026-01-01T00:00:00Z`.
`created_at__le`	`datetime`	—	Upper bound date-time range limit in ISO 8601 format (inclusive). Example: `2026-01-31T23:59:59Z`.

Examples

import httpx

# Example fetching the first page of failed SMS messages
response = httpx.get(
    "[https://api.ziett.co/c/v1/messages](https://api.ziett.co/c/v1/messages)",
    headers={
        "X-API-KEY": "zk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    },
    params={
        "page": 1,
        "size": 30,
        "status": ["FAILED", "UNDELIVERED"],
        "channel_type": "SMS",
    },
)

print(response.json())

curl -X GET "[https://api.ziett.co/c/v1/messages?page=1&size=30&status=FAILED&status=UNDELIVERED&channel_type=SMS](https://api.ziett.co/c/v1/messages?page=1&size=30&status=FAILED&status=UNDELIVERED&channel_type=SMS)" \
  -H "X-API-KEY: zk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const url = new URL("[https://api.ziett.co/c/v1/messages](https://api.ziett.co/c/v1/messages)");
url.searchParams.append("page", "1");
url.searchParams.append("size", "30");
url.searchParams.append("channel_type", "SMS");

// Pass array parameters by appending them multiple times
["FAILED", "UNDELIVERED"].forEach(status => url.searchParams.append("status", status));

const response = await fetch(url.toString(), {
  method: "GET",
  headers: {
    "X-API-KEY": "zk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  },
});

const data = await response.json();
console.log(data);

Responses

`200 OK` — Paginated List Retrieved

The query parameters were successfully evaluated and matched against your historical communication database.

{
  "entries": [
    {
      "id": "019b4b56-e704-7c30-83a0-527df63c3e00",
      "remitter_id": "019b4b56-e704-7c30-83a0-527df63c3e00",
      "campaign_id": null,
      "contact_id": "019b4b56-fa21-7210-91b1-127df63c3eef",
      "channel_type": "SMS",
      "channel_destination": "UNITEL",
      "target_e164": "+244990090990",
      "content": "Your verification code is 482910. It expires in 5 minutes.",
      "status": "DELIVERED",
      "error_code": null,
      "created_at": "2026-05-14T10:30:00.000000+00:00",
      "updated_at": "2026-05-14T10:30:04.000000+00:00"
    }
  ],
  "total": 1420,
  "page": 1,
  "size": 30,
  "pages": 48
}

Envelope Fields

Field	Type	Description
`entries`	`array[object]`	List of message details matching the criteria. See Message Detail Object.
`total`	`integer`	The absolute number of records matching the filters globally.
`page`	`integer`	The current page index returned.
`size`	`integer`	The number of records processed per page index.
`pages`	`integer`	Total count of accessible pages calculated from `total` and `size`.

Message Detail Object

Field	Type	Description
`id`	`uuid`	Unique tracking identifier for this message.
`remitter_id`	`uuid`	The identity signature or Sender ID resource used to issue the notification.
`campaign_id`	`uuid`	`null`
`contact_id`	`uuid`	`null`
`channel_type`	`string`	The delivery layout channel choice (`SMS`, `WHATSAPP`).
`channel_destination`	`string`	Resolved network operator carrier or delivery stack handler (e.g., `UNITEL`, `AFRICELL_AO`).
`target_e164`	`string`	Internationalized phone destination number formatted under standard E.164 constraints.
`content`	`string`	The message string content payload dispatched over the network.
`status`	`string`	The final or active structural operational state (`PENDING`, `SENT`, `DELIVERED`, `FAILED`, `UNDELIVERED`).
`error_code`	`string`	`null`
`created_at`	`datetime`	Timestamp marking when the notification request was ingested and stored.
`updated_at`	`datetime`	Timestamp capturing the most recent state or delivery receipt update.

`401 Unauthorized` — Invalid API Key

The X-API-KEY header is missing, malformed, or the key has been revoked.

{
  "code": "AUTH_INVALID_API_KEY",
  "message": "The provided API key is invalid or has been revoked.",
  "status": 401,
  "trace_id": "a1b2c3d4e5f644358a9e7011c123c831",
  "timestamp": "2026-05-14T10:30:00.000000+00:00",
  "service": "core"
}

`422 Unprocessable Entity` — Validation Error

One or more query attributes or formats are invalid (e.g., page boundaries out of bounds, malformed date-time string formats).

{
  "code": "VALIDATION_ERROR",
  "message": "One or more fields failed validation.",
  "status": 422,
  "trace_id": "f812a3bc91e044358a9e7011c456d901",
  "timestamp": "2026-05-14T10:30:00.000000+00:00",
  "service": "core",
  "fields": {
    "size": "Ensure this value is less than or equal to 200.",
    "created_at__ge": "Value must conform to a valid ISO 8601 date-time format structure."
  }
}

Rate Limits

This endpoint is limited to 60 requests per minute per API Key. See Rate Limits & Reliability for backoff strategies and retry guidance.