> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commune.email/llms.txt
> Use this file to discover all available pages before exploring further.
# List messages
> List messages filtered by inbox, domain, or sender identity.
```typescript TypeScript theme={null}
import { CommuneClient } from 'commune-ai';
const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });
const result = await commune.messages.list({
inboxId: 'inbox_abc123',
limit: 25,
direction: 'desc',
});
console.log(result.data.length); // up to 25
```
```python Python theme={null}
from commune import CommuneClient
client = CommuneClient()
result = client.messages.list(
inbox_id="inbox_abc123",
limit=25,
direction="desc",
)
print(len(result.data))
```
```bash MCP theme={null}
list_messages(
inbox_id="inbox_abc123",
limit=25
)
```
```bash cURL theme={null}
curl "https://api.commune.email/v1/messages?inbox_id=inbox_abc123&limit=25&order=desc" \
-H "Authorization: Bearer comm_..."
```
```bash CLI theme={null}
commune messages list --inbox-id inbox_abc123 --limit 25
```
```json 200 Success theme={null}
{
"data": [
{
"channel": "email",
"message_id": "49a3999c-0ce1-4ea6-ab68-e08a5c73e498",
"thread_id": "thread_f47ac10b-58cc-4372-a567-0e02b2c3d479",
"direction": "inbound",
"participants": [
{ "role": "sender", "identity": "customer@example.com" },
{ "role": "to", "identity": "support@mycompany.com" }
],
"content": "Hi, I need help with my order.",
"content_html": "Hi, I need help with my order.
",
"attachments": [],
"created_at": "2026-02-25T10:30:00.000Z",
"metadata": {
"created_at": "2026-02-25T10:30:00.000Z",
"subject": "Order help",
"inbox_id": "inbox_abc123",
"domain_id": "domain_xyz789",
"delivery_status": "delivered",
"has_attachments": false,
"attachment_count": 0,
"spam_checked": true,
"spam_score": 0.02,
"spam_action": "accept",
"spam_flagged": false,
"prompt_injection_checked": true,
"prompt_injection_detected": false,
"prompt_injection_risk": "none"
}
}
]
}
```
```json 400 Bad Request theme={null}
{
"error": "Provide at least one filter: sender, domain_id, or inbox_id"
}
```
```json 401 Unauthorized theme={null}
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
```
## Query Parameters
At least one of `inbox_id`, `domain_id`, or `sender` is required. The endpoint returns a 400 error if none are provided.
Filter messages to a specific inbox. Takes precedence over `domain_id` and `sender` when provided.
Filter messages to a specific domain. Used when `inbox_id` is not provided. Takes precedence over `sender`.
Filter messages by sender identity (email address). Used when neither `inbox_id` nor `domain_id` is provided.
Maximum number of results to return. Range: 1–1000.
Sort order by `created_at`. One of: `asc` (oldest first) or `desc` (newest first).
ISO 8601 date string. Return only messages created before this timestamp. Example: `2026-02-25T00:00:00.000Z`.
ISO 8601 date string. Return only messages created after this timestamp. Example: `2026-02-01T00:00:00.000Z`.
## Response
Array of message objects.
Always `"email"` for email messages.
Unique message identifier.
Thread this message belongs to. Format: `thread_`.
`"inbound"` for received messages, `"outbound"` for sent messages.
One of: `sender`, `to`, `cc`, `bcc`, `mentioned`, `participant`.
Email address of this participant.
Plain text body of the message.
HTML body of the message. `null` if no HTML body was present.
Array of attachment IDs associated with this message.
ISO 8601 timestamp when this message was created.
Email subject line.
ID of the inbox this message belongs to.
ID of the domain this message belongs to.
Full email address of the inbox (e.g. `support@mycompany.com`).
RFC 5322 `In-Reply-To` header value. Present on replies.
RFC 5322 `References` header values for thread chaining.
Current delivery status. One of: `sent`, `delivered`, `bounced`, `failed`, `complained`, `suppressed`, `blocked`, `credit_limit`.
ISO 8601 timestamp when the message was sent.
ISO 8601 timestamp when delivery was confirmed.
ISO 8601 timestamp of bounce event.
Human-readable bounce reason from the receiving server.
One of: `hard`, `soft`.
ISO 8601 timestamp of failure event.
Reason for delivery failure.
`true` if this message has one or more attachments.
Number of attachments on this message.
IDs of attachments linked to this message.
Whether spam analysis was performed on this message.
Spam probability score between 0.0 (clean) and 1.0 (spam).
Action taken based on spam analysis. One of: `accept`, `flag`, `reject`.
`true` if the message was flagged as spam.
List of reasons the message was flagged, if applicable.
Whether prompt injection analysis was performed.
`true` if a prompt injection attempt was detected in the message body.
Risk level of detected prompt injection. One of: `none`, `low`, `medium`, `high`, `critical`.
Rule-based prompt injection score between 0.0 and 1.0.
Comma-separated list of rule signals that triggered the score.
Structured data extracted from the message body when an extraction schema is configured on the inbox. Keys and value types are defined by your schema.
Structured extraction requires the **Business** plan or higher.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.