# Delete a conversation

DELETE /v1/threads/{thread_id}

Source: https://cherami.to/docs/api/threads/delete-thread



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`DELETE /v1/threads/{thread_id}`

Requires a [Claim-issued API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

`DELETE /v1/threads/{thread_id}` permanently deletes all messages currently in the conversation and their attachments. Confirm the exact conversation and full scope with the human. There is no trash or undo. Deletion requires the account's `can_delete` permission.

Returns the deletion result.

`id` is the canonical thread ID when members were selected; counts describe those selected messages. They are hidden from retrieval and search together. The inbox and saved drafts remain available. Sent-copy deletion does not cancel an already reserved send or refund its allowance.

Empty, missing or other-account threads return `404`; an account without deletion permission receives `403 operation_not_allowed`.

## Parameters [#parameters]

| Parameter   | Location | Required | Type   | Meaning                                        |
| ----------- | -------- | -------- | ------ | ---------------------------------------------- |
| `thread_id` | path     | Yes      | string | Owned Cherami resource ID returned by the API. |

## curl example [#curl-example]

Replace resource-ID placeholders with returned IDs. Supply `CHERAMI_API_KEY` through your private shell environment.

```sh
curl --silent --show-error --include --request DELETE \
  "https://cherami.to/v1/threads/THREAD_ID" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"
```

## Responses [#responses]

### HTTP 202 [#http-202]

Request accepted; inspect the response for its meaning.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[DeletedThread](#schema-deletedthread)

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "inbox_id": "11111111-1111-4111-8111-111111111111",
  "message_count": 0,
  "received_count": 0,
  "sent_count": 0,
  "status": "deletion_pending",
  "message": "Example"
}
```

### HTTP 401 [#http-401]

`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.

* `X-Request-ID`: Support correlation ID, not an idempotency key.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 403 [#http-403]

`operation_not_allowed`: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 500 [#http-500]

`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

## Schema: DeletedThread [#schema-deletedthread]

| Field            | Required | Type                 | Meaning and constraints                                                        |
| ---------------- | -------- | -------------------- | ------------------------------------------------------------------------------ |
| `id`             | Yes      | string               | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
| `inbox_id`       | Yes      | string               | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
| `message_count`  | Yes      | integer              | `minimum`: `0`                                                                 |
| `received_count` | Yes      | integer              | `minimum`: `0`                                                                 |
| `sent_count`     | Yes      | integer              | `minimum`: `0`                                                                 |
| `status`         | Yes      | `"deletion_pending"` |                                                                                |
| `message`        | Yes      | string               |                                                                                |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                                                       |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------- |
| `code`    | Yes      | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
| `message` | Yes      | string | Human-readable context, not a stable string to match.                                         |

[HTTP conventions, errors and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)