---
title: "List conversations"
description: "Your inbox's conversations, newest activity first, as Emails → Received shows them: each received message and the replies and forwards sent from it are one conversation. `GET /api/v1/email/threads`"
url: https://www.unitpost.com/docs/email/get-email-threads
section: "Email API reference"
updated: 2026-10-13
---
# List conversations

`GET /api/v1/email/threads`

Your inbox's conversations, newest activity first, as Emails → Received shows them: each received message and the replies and forwards sent from it are one conversation. Every conversation is listed: read state and Spam are the dashboard's. `q` searches the subject, the sender and the opening words. Page with `next_cursor` as `after`. `snippet` is null when the newest message is one you sent (or a copy of your own send): sent bodies aren't on the API, and `q` never matches a withheld snippet, so a page can be shorter than `limit` while `has_more` is true. `q` shares the search rate policy. Any other query key is a `422`. Requires the `emails:read` capability.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | no | Search the subject, sender and opening words. |
| `limit` | query | integer | no | 1–100 (default 50). |
| `after` | query | string | no | The previous page's `next_cursor`. |

## Response fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | — |
| `id` | string | yes | — |
| `subject` | string \| null | yes | — |
| `last_message_at` | string | yes | — |
| `last_direction` | enum | yes | One of: `inbound`, `outbound`. |
| `snippet` | string \| null | yes | The newest received message's opening words; null when the newest message is one you sent. |
| `from` | string \| null | yes | The other party: the newest received message's sender. |
| `from_name` | string \| null | yes | — |
| `inbox_address` | string \| null | yes | Your address it came in on (the newest received message's To). |
| `message_count` | integer | yes | — |
| `has_attachments` | boolean | yes | — |
| `flagged` | boolean | yes | A received message was flagged spam or virus, or failed SPF, DKIM or DMARC. |
| `replied` | boolean | yes | A reply or forward was sent from this conversation. |

## Responses

| Status | Description |
| --- | --- |
| 200 | A page of conversations. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope. |
| 422 | A bad `limit` or `after`, or an unknown query key. |

## Example request

```bash
curl -X GET 'https://www.unitpost.com/api/v1/email/threads' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
```

## Example response (200)

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "email_thread",
      "id": "id_123",
      "subject": "Welcome to Acme",
      "last_message_at": "2026-01-01T00:00:00.000Z",
      "last_direction": "inbound",
      "snippet": "string",
      "from": "you@yourdomain.com",
      "from_name": "string",
      "inbox_address": "string",
      "message_count": 1,
      "has_attachments": false,
      "flagged": false,
      "replied": false
    }
  ],
  "next_cursor": "string"
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Laravel, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/email/get-email-threads
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json