List messages

Time	Status	User Agent
Retrieving recent requests…

The messages archive API gives you programmatic access to your archived emails and SMS. Use it to retrieve message content and metadata for customer support, compliance reporting, or bulk data exports.

📘
Note
The request body determines the scope of the request. Include either customer_ids or recipient to list messages for specific customers, or omit both to list across the entire project.

Authentication and access

The API uses Basic authentication. Include your API key ID and secret key in the request header:

Authorization: Basic <api_key>

You also need the messages archive permission enabled in your project's API settings. See Setting up API groups for instructions.

⚠️
Warning
This endpoint applies a rate limit of 300 requests per minute. If this is reached, the endpoint returns 429 Too Many Requests with the following headers:

Retry-After: <seconds> : how long until the window resets.

X-RateLimit-Limit : the limit value.

X-RateLimit-Remaining : remaining requests in the window.

X-RateLimit-Reset : UNIX timestamp when the window resets.

Request body example

{
  "customer_ids": { "registered": "[email protected]" },
  "channel": "email",
  "limit": 50,
  "from_date": 1700000000.0,
  "to_date": 1710000000.0,
  "from_cursor": "a1b2c3d4-e5f6-7890-abcd-ef1234567890#9a8b7c6d...#email"
}

Response examples

{
  "success": true,
  "data": [
    {
      "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "customer_id": "60b8d295f1a2c3001f9e4a12",
      "message_id": "65a1b2c3d4e5f60011223344",
      "channel": "email",
      "sender": "[email protected]",
      "recipient": "[email protected]",
      "subject": "Welcome to our platform",
      "sent_timestamp": 1705000000.0,
      "campaign_name": "Onboarding",
      "campaign_id": "64f1a2b3c4d5e60011223344",
      "action_id": 1,
      "action_name": "Welcome email",
      "sender_name": "Company",
      "preheader": "Get started with your new account"
    }
  ],
  "next_cursor": "a1b2c3d4-e5f6-7890-abcd-ef1234567890#9a8b7c6d...#email"
}

{
  "success": true,
  "data": [
    {
      "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "customer_id": "60b8d295f1a2c3001f9e4a12",
      "message_id": "65a1b2c3d4e5f60011223355",
      "channel": "sms",
      "sender": "+1234567890",
      "recipient": "+0987654321",
      "subject": null,
      "sent_timestamp": 1705000000.0,
      "campaign_name": "SMS Promo",
      "campaign_id": "64f1a2b3c4d5e60011223355",
      "action_id": 2,
      "action_name": "Promo SMS"
    }
  ],
  "next_cursor": null
}

{
  "success": true,
  "data": {
    "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "60b8d295f1a2c3001f9e4a12",
    "message_id": "65a1b2c3d4e5f60011223344",
    "channel": "email",
    "sender": "[email protected]",
    "recipient": "[email protected]",
    "subject": "Welcome to our platform",
    "sent_timestamp": 1705000000.0,
    "campaign_name": "Onboarding",
    "campaign_id": "64f1a2b3c4d5e60011223344",
    "action_id": 1,
    "action_name": "Welcome email",
    "sender_name": "Company",
    "preheader": "Get started with your new account",
    "email": "<html><body><h1>Welcome!</h1></body></html>",
    "attachments": [
      {
        "filename": "guide.pdf",
        "size": 102400,
        "content_type": "application/pdf"
      }
    ]
  }
}

{
  "success": true,
  "data": {
    "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "60b8d295f1a2c3001f9e4a12",
    "message_id": "65a1b2c3d4e5f60011223355",
    "channel": "sms",
    "sender": "+1234567890",
    "recipient": "+0987654321",
    "subject": null,
    "sent_timestamp": 1705000000.0,
    "campaign_name": "SMS Promo",
    "campaign_id": "64f1a2b3c4d5e60011223355",
    "action_id": 2,
    "action_name": "Promo SMS",
    "message": "Hi! Check out our latest offers."
  }
}

Email data fields

Each email object in the response's data array contains the following fields:

Field	Type	Description	Example
`project_id`	string	Project UUID.	a1b2c3d4-e5f6-7890-abcd-ef1234567890
`customer_id`	string	Internal customer ID (ObjectId).	60b8d295f1a2c3001f9e4a12
`message_id`	string	Message ID (ObjectId).	65a1b2c3d4e5f60011223344
`channel`	string	Always "email".	email
`sender`	string	Sender email address.	[email protected]
`sender_name`	string \| null	Sender display name.	Company
`recipient`	string	Recipient email address.	[email protected]
`subject`	string \| null	Email subject line.	Welcome to our platform
`preheader`	string \| null	Email preheader text.	Get started with your new account
`sent_timestamp`	float \| null	Unix timestamp.	1705000000.0
`campaign_id`	string \| null	Campaign ID.	64f1a2b3c4d5e60011223344
`campaign_name`	string \| null	Campaign or scenario name.	Onboarding
`action_id`	int \| null	Action node ID.	1
`action_name`	string \| null	Action node name.	Welcome email

📘
Note
Full email HTML isn't included in the list messages response. Get a single message to retrieve the full HTML.

SMS data fields

Each SMS object in the response's data array contains the following fields:

Field	Type	Description	Example
`project_id`	string	Project UUID.	a1b2c3d4-e5f6-7890-abcd-ef1234567890
`customer_id`	string	Internal customer ID (ObjectId).	60b8d295f1a2c3001f9e4a12
`message_id`	string	Message ID (ObjectId).	65a1b2c3d4e5f60011223355
`channel`	string	Always "sms".	sms
`sender`	string	Sender phone number or alpha sender.	+1234567890
`recipient`	string	Recipient phone number.	+0987654321
`subject`	null	Always null for SMS.	null
`sent_timestamp`	float \| null	Unix timestamp.	1705000000.0
`campaign_id`	string \| null	Campaign ID.	64f1a2b3c4d5e60011223355
`campaign_name`	string \| null	Campaign or scenario name.	SMS Promo
`action_id`	int \| null	Action node ID.	2
`action_name`	string \| null	Action node name.	Promo SMS

Limitations and behavior

Ordering: Newest message on top.
Mid-scan messages: Messages written during an active scan may be missed if their customer prefix was already scanned. They appear in the next export.
Project-wide scans: Results are grouped by customer, not sorted chronologically across all customers.
Response times: This API isn't designed for real-time use. Expect slower response times than other Data API endpoints.

Note

Authentication and access

Warning

Request body example

Response examples

Email data fields

Note

SMS data fields

Limitations and behavior

200

400Validation errors (invalid channel, limit out of range, bad cursor, bad ObjectId, etc.)

401Unauthorized. No/incorrect authentication credentials provided.

403Forbidden. Missing message_archive permission or module not enabled.

404Not Found

429Too Many Requests. Rate limited.

`message_archive` permission or module not enabled.