Customer.io
v1.0.0
OpenAPI 3.1.0

Lookup messages sent to a customer

US region

Client Libraries
Shell Curl

Lookup messages sent to a customer

​

Returns information about the deliveries sent to a person. Provide query parameters to refine the data you want to return.

Use the start_ts and end_ts to find messages within a time range. If your request doesn't include start_ts and end_ts parameters, we'll return the most recent 6 months of messages. If your start_ts and end_ts range is more than 6 months, we'll return 6 months of data from the most recent timestamp in your request. 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.

Path Parameters
  • customer_id
    Type: string
    required

    The ID of the customer you want to perform an operation against.

Query Parameters
  • id_type
    Type: stringenum

    The type of customer_id you want to use to reference a person. If you don't provide this parameter, we assume that the customer_id in your request is a person's id. You can use email and phone only if they're enabled as identifiers in your workspace settings; otherwise the request returns 400. Reference phone values in E.164 format, like +14155552671, and URL-encode the leading + as %2B.

    values
    • id
    • email
    • phone
    • cio_id
  • 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.

  • start_ts
    Type: integerFormat: unix timestamp

    The beginning timestamp for your query.

  • end_ts
    Type: integerFormat: unix timestamp

    The ending timestamp for your query.

Responses
  • application/json
  • 404

    The customer_id does not exist.

  • 429

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

Request Example for get/v1/customers/{customer_id}/messages
curl 'https://api.customer.io/v1/customers/12345/messages?id_type=id&start=&limit=50&start_ts=1&end_ts=1' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "messages": [
    {
      "id": "string",
      "deduplicate_id": "string",
      "customer_id": "string",
      "campaign_id": 1,
      "action_id": 1,
      "recipient": "string",
      "subject": "string",
      "metrics": {
        "delivered": 1,
        "sent": 1
      },
      "created": 1,
      "failure_message": null,
      "newsletter_id": null,
      "content_id": null,
      "broadcast_id": null,
      "type": "email",
      "forgotten": true
    }
  ]
}

Returns an array of message objects. Each object represents a message that you sent a customer.