Delete a conversation
DELETE /v1/threads/{thread_id}
Read as Markdown ↗DELETE /v1/threads/{thread_id}
Requires a Claim-issued API key: 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
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
thread_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
curl --silent --show-error --include --request DELETE \
"https://cherami.to/v1/threads/THREAD_ID" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 202
Request accepted; inspect the response for its meaning.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/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
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
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.
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.
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.
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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
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 · Download OpenAPI 3.1