---
title: "List messages"
method: GET
path: "/v1/messages"
tags: ["Messages"]
---

# List messages

`GET /v1/messages`

Return a list of deliveries, including metrics for each delivery, for messages in your workspace. The request body contains filters determining the deliveries you want to return information about.

Use the `start_ts` and `end_ts` parameters to find messages within a time range. We limit your requests to 6 months. If your request doesn't include `start_ts` and `end_ts` parameters, we'll return the most recent 6 months of deliveries. If `start_ts` is greater than 6-months before `end_ts`, we only send back 6 months of data. If only `end_ts` is specified, we return 6 months of data before this timestamp. If only `start_ts` is specified, we then set the `end_ts` to the current time and deliver 6 months of data prior to this timestamp. Timestamps reflect when deliveries were created in our system, not when they were actually sent to recipients. There may be a delay between creation and sending.

## Response `200`

Returns an array of message objects.

- object
  - `messages` MessageObject[] — Each object in the array describes an individual message delivery. The object contains keys for all possible parents of the message (`newsletter_id`, `broadcast_id`, etc) but only the parents of the delivery are populated. Other parent IDs are null.
    - `id` string — The identifier for a delivery—the instance of a message intended for an individual recipient.
    - `deduplicate_id` string — An identifier in the format `id:timestamp` where the id is for the object you're working with (Automations, Deliveries, Exports, Identities, Newsletters, Segments, and Templates), and the timestamp is the last time the object was updated.
    - `message_template_id` integer — The identifier of the message template used to create a message.
    - `customer_id` string, nullable — The ID of a customer profile, analogous to a "person" in the UI. If your workspace supports multiple identifiers (email and ID), this value can be null.
    - `customer_identifiers` CustomerIdentifiers — Identifiers for the person in a response—`id`, `cio_id`, and `email`. Unset `id` or `email` values are `null`. We recommend this object over the less descriptive `customer_id`. This object doesn't include `phone`, even if your workspace uses phone numbers as an identifier; look for the person's `phone` attribute instead.
      - `email` string, email, nullable, required — A person's email address, if set.
      - `id` string, nullable, required — A person's unique ID, if set. This is the same as the `customer_id` if present.
      - `cio_id` string, required — A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers.
    - `recipient` string — The recipient address for an action.
    - `subject` string — The subject line for an `email` action.
    - `metrics` MessageMetrics — Metrics for an individual instance of a message; each item in the object represents the timestamp when a message achieved a particular metric. This object only contains metrics that have been recorded.
      - `bounced` integer — The timestamp when the message `bounced`.
      - `clicked` integer — The timestamp when the message was `clicked`.
      - `human_clicked` integer — The number of `clicked` messages excluding machine clicks. This metric is reliable starting April 20, 2025. [Learn more](/messaging/metrics/analytics/#delivery-metrics).
      - `prefetch_clicked` integer — The number of `clicked` messages attributed to machines. This metric is reliable starting April 20, 2025.
      - `converted` integer — The timestamp when the message was `converted`.
      - `created` integer — The timestamp when the message was `created`.
      - `delivered` integer — The timestamp when the message was `delivered`.
      - `drafted` integer — The timestamp when the message was `drafted`.
      - `dropped` integer — The timestamp when the message was `dropped`.
      - `failed` integer — The timestamp when the message `failed`.
      - `opened` integer — The timestamp when the message was `opened`.
      - `human_opened` integer — The number of `opened` messages excluding machine opens. This metric is reliable starting March 20, 2025. [Learn more](/messaging/metrics/analytics/#delivery-metrics).
      - `prefetch_opened` integer — The number of `opened` messages attributed to machines. This metric is reliable starting March 20, 2025.
      - `sent` integer — The timestamp when the message was `sent`.
      - `spammed` integer — The timestamp when the message was marked as spam.
      - `undeliverable` integer — The timestamp when the message became `undeliverable`.
      - `unsubscribed` integer — The timestamp when a person unsubscribed based on this message.
    - `created` integer — The date time when the referenced ID was created.
    - `failure_message` string, nullable — Explains why a message failed, if applicable.
    - `campaign_id` integer — The identifier for an automation.
    - `action_id` integer — The identifier for an action.
    - `parent_action_id` integer — The ID of the parent action, if the action occurred within an automation and has a parent (like a randomized split, etc).
    - `newsletter_id` integer — The identifier for a newsletter.
    - `content_id` integer — The identifier for a message in a newsletter. Newsletters can have multiple content IDs (for multi-language messages or A/B tests).
    - `broadcast_id` integer — The identifier for a broadcast.
    - `trigger_event_id` string — The id of the event that triggered an event-triggered automation (not an API-triggered broadcast).
    - `forgotten` boolean — If true message contents are not retained by Customer.io.
    - `tracked_responses` object — Tracked in-app survey responses, keyed by response option name. Present only when `get_tracked_responses` is `true`.
    - `type` 'email' | 'webhook' | 'twilio' | 'push' | 'in_app' | 'slack' | 'whatsapp' | 'live_notification' — The type of message or action for a delivery, automation action, or related object. Includes channels that newsletters do not support (for example, `slack` and `whatsapp`).

## Other responses

- `400` — The request was malformed.
- `429` — Your request is over the 10-per-second limit.

---

[API](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference.md) · [All operations](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/customer/customer-io-journeys-api-reference/revisions/4b391af7cb06/schema)