---
title: "Email threads API"
description: "Work your inbox as conversations: list and read them, mark them read, report spam, block a sender, reply or forward, and delete a conversation, as Emails → Received does in the dashboard."
url: https://www.unitpost.com/docs/email/email-threads
section: "Email API reference"
updated: 2026-10-13
---
# Email threads API

> Work your inbox as conversations: list and read them, mark them read, report spam, block a sender, reply or forward, and delete a conversation, as Emails → Received does in the dashboard.

Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/email/email-threads.

## Operations

### `GET /api/v1/email/threads`

List conversations

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.

Reference: https://www.unitpost.com/docs/email/get-email-threads ([Markdown](https://www.unitpost.com/docs/email/get-email-threads.md))

### `GET /api/v1/email/threads/{id}`

Retrieve a conversation

One conversation, oldest message first: what you received (bodies, `reply_to`, verdicts, attachments) and what you sent from it (status and recipients, no body). A long conversation comes in pages, newest first: this read holds its newest `limit` messages (fewer when their bodies are large), and `older_cursor` passed as `before` reads the messages before them, as the inbox's "Show earlier messages" does. Answer a message with [Reply to a conversation](https://www.unitpost.com/docs/email/post-email-threads-id-reply). Requires the `emails:read` capability.

Reference: https://www.unitpost.com/docs/email/get-email-threads-id ([Markdown](https://www.unitpost.com/docs/email/get-email-threads-id.md))

### `DELETE /api/v1/email/threads/{id}`

Delete a conversation

Delete a conversation for good, as the inbox's Delete does. Its received messages are erased (they still count toward usage, and never come back); replies and forwards sent from it stay on your sent emails. It can't be undone. Also requires `emails:read`. Requires the `emails:send` capability.

Reference: https://www.unitpost.com/docs/email/delete-email-threads-id ([Markdown](https://www.unitpost.com/docs/email/delete-email-threads-id.md))

### `POST /api/v1/email/threads/{id}/reply`

Reply to a conversation

Reply, reply all or forward one received message of the conversation (`received_email_id`), as the inbox does: your `text` and/or `html` go on top and the original is quoted under them; a reply carries In-Reply-To and References; a forward carries the attachments you list in `forward_attachment_ids`. The message joins the conversation and the conversation is marked read. For a reply, send `to` the message's `reply_to` addresses, else its `from`. It goes out now (no `scheduled_at`) through the same checks as any send. Pass an `Idempotency-Key`: a retry with it never sends twice. A copy of one of your own sends (`sent_by_us`) is never forwarded or quoted, since what you send isn't readable through the API: a reply to it goes without the quote, and a forward of it is a `403`. Also requires `emails:read` (a reply quotes mail). Requires the `emails:send` capability.

Reference: https://www.unitpost.com/docs/email/post-email-threads-id-reply ([Markdown](https://www.unitpost.com/docs/email/post-email-threads-id-reply.md))