# Delete an inbox

DELETE /v1/inboxes/{inbox_id}

Source: https://cherami.to/docs/api/inboxes/delete-inbox



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

`DELETE /v1/inboxes/{inbox_id}`

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

`DELETE /v1/inboxes/{inbox_id}` returns `202`.

Permanently deletes the inbox and its received mail, drafts, sent copies, attachments, and threads, including unfinished messages. Confirm the specific inbox and destructive scope with the human before calling it, especially with shared access. The API does not provide a separate approval step.

The slot is freed and the address is permanently retired. Future incoming mail is rejected. Retrieval and new sends from the deleted inbox return `404`. Other inboxes and the credential remain unchanged. There is no undo or sending-quota refund.

Repeating DELETE is safe and can return `202` or `404`. Missing or other-account resources also return `404`. The service support inbox `hello@cherami.to` returns `409 protected_inbox` to its owner.

[Deletion guide and manual account deletion](https://cherami.to/docs/guides/deletion)

## Parameters [#parameters]

| Parameter  | Location | Required | Type   | Meaning                                        |
| ---------- | -------- | -------- | ------ | ---------------------------------------------- |
| `inbox_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/inboxes/INBOX_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`.

[Deleted](#schema-deleted)

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "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 409 [#http-409]

`protected_inbox`: The service support inbox cannot be deleted.

* `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: Deleted [#schema-deleted]

| Field     | Required | Type                 | Meaning and constraints                                                        |
| --------- | -------- | -------------------- | ------------------------------------------------------------------------------ |
| `id`      | Yes      | string               | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
| `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)