Customer.io
v1.0.0
OpenAPI 3.1.0

List messages

US region

Client Libraries
Shell Curl

List 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.

Query Parameters
  • start
    Type: string

    The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

  • limit
    Type: integer
    max:  
    1000

    The maximum number of results you want to retrieve per page.

  • type
    Type: stringenum

    The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

    values
    • email
    • webhook
    • twilio
    • whatsapp
    • slack
    • push
    • in_app
    • live_notification
  • metric
    Type: stringenum

    Determines the metric(s) you want to return.

    values
    • attempted
    • sent
    • delivered
    • opened
    • clicked
  • drafts
    Type: boolean

    If true, your request returns drafts rather than active/sent messages.

  • campaign_id
    Type: integer

    The campaign you want to filter for.

  • newsletter_id
    Type: integer

    The newsletter you want to filter for.

  • action_id
    Type: integer

    The action you want to filter for.

  • start_ts
    Type: integerFormat: unix timestamp

    The beginning timestamp for your query.

  • end_ts
    Type: integerFormat: unix timestamp

    The ending timestamp for your query.

  • get_tracked_responses
    Type: boolean

    If true, the response includes tracked_responses for each message—an object containing tracked response option names for in-app survey responses.

Responses
  • application/json
  • 400

    The request was malformed.

  • 429

    Your request is over the 10-per-second limit.

Request Example for get/v1/messages
curl 'https://api.customer.io/v1/messages?start=&limit=50&type=email&metric=attempted&drafts=true&campaign_id=1&newsletter_id=1&action_id=1&start_ts=1&end_ts=1&get_tracked_responses=false' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "messages": [
    {
      "id": "ag1q6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=",
      "deduplicate_id": "ag1q6QWq6QUBAAF4_CGoeVX7mFkDbRFu7ek=:1619137768",
      "msg_template_id": 43,
      "action_id": 215,
      "parent_action_id": null,
      "customer_id": null,
      "recipient": "person@example.com",
      "subject": "Did you get that thing I sent you?",
      "metrics": {
        "delivered": 1619137768,
        "sent": 1619137768
      },
      "created": 1619137767,
      "failure_message": null,
      "newsletter_id": null,
      "content_id": null,
      "campaign_id": 23,
      "broadcast_id": null,
      "trigger_event_id": null,
      "type": "email",
      "forgotten": false
    }
  ]
}

Returns an array of message objects.