List archived messages

post

https://api.exponea.com/data/v2/projects/{project_id}/message-archive/list

Recent Requests

Log in to see full request history

Time	Status	User Agent
Retrieving recent requests…

Loading…

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"
}

{
  "recipient": "[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 metadata 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
The full HTML email isn't included in the list message response. Get a single archived message to retrieve the full HTML.

SMS metadata 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

📘
Note
The SMS message's content isn't included in the list message response. Get a single archived message to retrieve the message.

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.

Path Params

project_id

string

required

Your project's ID.

Body Params

customer_ids

object

Dictionary of external IDs. For example, {"registered": "..."}. Omit this parameter for project-wide listing.

Required if recipient is not used.

recipient

string

Recipient email address or phone number. Omit for project-wide listing.

Required if customer_ids is not used.

channel

string

email or sms. Omit to return all channels.

from_date

float

Start of the date range (Unix timestamp, inclusive).

to_date

float

End of the date range (Unix timestamp, inclusive).

limit

integer

Defaults to 50

Records to return per response. Minimum value can be 1, and maximum 200.

from_cursor

string

Pagination cursor. Pass the next_cursor value from the previous response.

Headers

Authorization

string

required

Defaults to Basic <base64(api_key_id:secret_key)>

Responses

Language

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json