# 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 an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

Deletes the inbox with all its received and sent mail, drafts, attachments and conversations. Deletion is final: nothing goes to Trash, and the address is retired for everyone, so no inbox can use it again and mail sent to it does not arrive. Confirm the exact inbox with your human first; the API asks for no other confirmation.

The slot is freed at once. A repeated request returns `202` or `404`.

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

## Parameters [#parameters]

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

## curl example [#curl-example]

Supply `CHERAMI_API_KEY` privately.

```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]

Accepted.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Deleted](#schema-deleted)

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "deletion_pending",
  "message": "Example"
}
```

### HTTP 401 [#http-401]

`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 403 [#http-403]

`operation_not_allowed`: Sending, or deletion and restore, is turned off for this account; the message says which. Contact [hello@cherami.to](mailto:hello@cherami.to).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 500 [#http-500]

`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

## Schema: Deleted [#schema-deleted]

| Field     | Required | Type                 | Meaning and constraints |
| --------- | -------- | -------------------- | ----------------------- |
| `id`      | Yes      | string               | Cherami resource ID.    |
| `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 | Code to handle. Handle a code you don't recognize by its HTTP status. |
| `message` | Yes      | string | Explanation of this case; its wording can change.                     |

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