---
title: "Trash or delete a thread"
method: DELETE
path: "/v1/threads/{id}"
tags: ["Threads"]
---

# Trash or delete a thread

`DELETE /v1/threads/{id}`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/threads/{id}`
- Auth: HTTP bearer

**Requires scope:** `manage` or `inbox` (`inbox` only in a signed-in dashboard session, and only to move to trash: `permanent=true` takes `manage`; no API key or app can hold it). Moves the thread to trash (`deleted: false`, the thread returned). Sent again for a thread already in trash it changes nothing, so a retried request never destroys mail. With `permanent=true` it deletes the thread for good, from any folder: its messages' content, raw email and attachments are removed, and `thread.deleted` is emitted. Trash is also emptied automatically 30 days after a thread was moved there. A test key cannot trash or delete a thread holding live mail (403 `live_mode_required`). An app connected by sign-in may move a thread to trash but not delete it for good: with `permanent=true` it gets 403 `connected_app_not_allowed`.

## Path parameters

- `id` string, required

## Query parameters

- `permanent` boolean

## Response `200`

The trashed thread, or the id of the thread deleted for good.

- union
  - object
    - `id` string, required: Thread id (`thrd_…`).
    - `agent_id` string, required: Id (`agt_…`) of the agent the thread belongs to; a thread holds one agent's mail only.
    - `subject` string: The subject of the thread's first message, without one leading `Re:`, `Fwd:` or `Fw:`. Empty when that message had no subject.
    - `root_message_id` string: Id of the message that started the thread: `msg_…` for one the agent sent, `rcv_…` for one it received.
    - `last_message_id` string: Id of the message that joined the thread most recently (`msg_…` or `rcv_…`).
    - `last_message_at` string, date-time: When the latest message joined the thread. The thread list is ordered by it, newest first.
    - `message_count` integer, required: How many messages have joined the thread, sent and received.
    - `participants` string[]: Every address the thread has involved, in lower case and without repeats: the agent's own, the senders of received mail and the recipients of sent mail.
    - `labels` string[]: Label names, up to 50, each at most 64 characters. Any such name works; names that match a label object also appear in `label_ids`.
    - `label_ids` string[], required: Ids (`lbl_…`) of the label objects whose names are on this thread.
    - `status` 'open' | 'closed' | 'archived', required: `open` (every new thread), `closed` or `archived`, changed with PATCH. `archived` goes with folder `archive`, and only an `open` thread takes in new mail matched by its subject (mail from someone already in the thread).
    - `read` boolean, required: False once new mail arrives; set it with PATCH.
    - `folder` 'inbox' | 'archive' | 'spam' | 'trash' | 'sent', required: `inbox`, `archive`, `spam`, `trash` or `sent`. `archive` goes with status `archived`. `sent` holds a thread whose messages are all ones the agent sent, until a reply moves it to the inbox. Threads in trash are deleted for good 30 days after they were trashed.
    - `trashed_at` string, date-time: When the thread was moved to trash. Present only while it is there.
    - `test_mode` boolean, required: True when the thread holds no live mail: every message in it was sent with a test key (`mk_test_…`) or delivered through `POST /v1/test/inbound`. A thread with any live message is live. Its `thread.*` events carry the same `test_mode`, and `GET /v1/threads` lists a key's own mode unless `mode` says otherwise.
    - `created_at` string, date-time, required: When the thread was created, with its first message.
    - `updated_at` string, date-time: When the thread last changed: a message joined it, or its read state, folder, status or labels changed.
    - `deleted` false, required: Always `false` here: the thread was moved to trash, not deleted, and is returned in full. Unless it is moved out first, it is deleted for good once it has been in trash for 30 days.
  - object
    - `id` string, required: Id (`thrd_…`) of the thread deleted for good.
    - `deleted` true, required: Always `true` here, for `permanent=true`: the thread is gone for good, with its messages' content, raw email and attachments.

## Other responses

- `400`: Invalid request — malformed JSON or a field failed validation. Also `feature_not_enabled` when this server has a feature switched off (custom domains before they are available).
- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `404`: Resource not found in this workspace, or the agent a send names is archived (`agent_archived`).
- `409`: Conflict — duplicate resource, an in-progress idempotent request, a draft or scheduled message that started sending while it was being changed, or a thread deleted for good while one of its messages is being sent (`duplicate_resource`); or an agent name more than one agent has (`agent_name_conflict`: use the agent's id); or a status change on an archived agent, since archiving cannot be undone (`agent_archived`).
- `500`: Internal server error.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)