# List Trash GET /v1/inboxes/{inbox_id}/trash Source: https://cherami.to/docs/api/trash/list-trash {/* Generated from apps/web/openapi. Edit the contract, not this file. */} `GET /v1/inboxes/{inbox_id}/trash` Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`. Lists the inbox's deleted messages that can still be restored, most recently deleted first. `kind` (`received` or `sent`) picks the restore endpoint: [received](https://cherami.to/docs/api/trash/restore-message) or [sent](https://cherami.to/docs/api/trash/restore-sent-message). `restorable_until` is seven days after `deleted_at`; after it the message is gone for good. A deleted conversation appears as its separate messages. Mail deleted with its inbox never appears here. ## Parameters [#parameters] | Parameter | Location | Required | Type | Meaning | | ---------- | -------- | -------- | ------- | ------------------------------------------------------------------------------- | | `inbox_id` | path | Yes | string | Cherami resource ID returned by the API. | | `limit` | query | No | integer | Results per page. `minimum`: `1` `maximum`: `100` `default`: `20` | | `cursor` | query | No | string | next\_cursor from the previous page. Keep the URL, filters and order unchanged. | ## curl example [#curl-example] Supply `CHERAMI_API_KEY` privately. ```sh curl --silent --show-error --include --request GET \ "https://cherami.to/v1/inboxes/INBOX_ID/trash" \ --header "Authorization: Bearer $CHERAMI_API_KEY" ``` ## Responses [#responses] ### HTTP 200 [#http-200] Success. * `X-Request-ID`: Identifies this request; include it when reporting a problem. Content type: `application/json`. | Field | Required | Type | Meaning and constraints | | ------------- | -------- | ----------------------------------------- | ----------------------- | | `messages` | Yes | array of [TrashEntry](#schema-trashentry) | | | `next_cursor` | Yes | string or null | | ```json { "messages": [], "next_cursor": null } ``` ### HTTP 400 [#http-400] `invalid_limit`: Use an integer from 1 to 100. `invalid_cursor`: Send a cursor only to the listing, filters and order that returned it, or restart from the first page. * `X-Request-ID`: Identifies this request; include it when reporting a problem. Content type: `application/json`. [Error](#schema-error) ### HTTP 401 [#http-401] `unauthorized`: Send a valid API key as `Authorization: Bearer `. 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 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) ### HTTP 503 [#http-503] `content_unavailable`: Stored content could not be read. Retry later. * `X-Request-ID`: Identifies this request; include it when reporting a problem. Content type: `application/json`. [Error](#schema-error) ## Schema: TrashEntry [#schema-trashentry] A deleted message that can still be restored; kind picks the restore endpoint. from is null for a received message that never became ready. Exactly one of these shapes applies. ### Alternative 1 [#alternative-1] | Field | Required | Type | Meaning and constraints | | ------------------ | -------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Yes | string | Cherami resource ID. | | `kind` | Yes | `"received"` | | | `inbox_id` | Yes | string | Cherami resource ID. | | `subject` | Yes | string or null | | | `from` | Yes | [ParsedAddress](#schema-parsedaddress) or null | | | `envelope_from` | Yes | string | SMTP sender; can be a bounce address. | | `deleted_at` | Yes | string | UTC timestamp with milliseconds. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | | `restorable_until` | Yes | string | Seven days after deleted\_at; the message can't be restored after it. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | ### Alternative 2 [#alternative-2] | Field | Required | Type | Meaning and constraints | | ------------------ | -------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Yes | string | Cherami resource ID. | | `kind` | Yes | `"sent"` | | | `inbox_id` | Yes | string | Cherami resource ID. | | `subject` | Yes | string or null | | | `to` | Yes | array of [Mailbox](#schema-mailbox) | | | `deleted_at` | Yes | string | UTC timestamp with milliseconds. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | | `restorable_until` | Yes | string | Seven days after deleted\_at; the message can't be restored after it. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` | ## Schema: ParsedAddress [#schema-parsedaddress] Mailbox or group from the message headers, written by the sender and not verified. Exactly one of these shapes applies. ### Alternative 1 [#alternative-1-1] | Field | Required | Type | Meaning and constraints | | --------- | -------- | ------ | ----------------------- | | `name` | Yes | string | | | `address` | Yes | string | | ### Alternative 2 [#alternative-2-1] | Field | Required | Type | Meaning and constraints | | ------- | -------- | --------------- | ----------------------- | | `name` | Yes | string | | | `group` | Yes | array of object | | #### `group` fields [#group-fields] | Field | Required | Type | Meaning and constraints | | --------- | -------- | ------ | ----------------------- | | `name` | Yes | string | | | `address` | Yes | string | | ## Schema: Mailbox [#schema-mailbox] | Field | Required | Type | Meaning and constraints | | --------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `address` | Yes | string | Bare address such as [alex@example.com](mailto:alex@example.com): ASCII, at most 254 characters and 64 before the @. `maxLength`: `254` | | `name` | No | string | Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters. `x-max-utf8-bytes`: `256` | Unknown fields are rejected. ## 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)