List Trash
GET /v1/inboxes/{inbox_id}/trash
Read as Markdown ↗GET /v1/inboxes/{inbox_id}/trash
Requires an API key: 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 or sent. 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
| 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
Supply CHERAMI_API_KEY privately.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/inboxes/INBOX_ID/trash" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
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 | |
next_cursor | Yes | string or null |
{
"messages": [],
"next_cursor": null
}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.
HTTP 401
unauthorized: Send a valid API key as Authorization: Bearer <key>. If the key stopped working, get a new one through recovery.
X-Request-ID: Identifies this request; include it when reporting a problem.WWW-Authenticate:"Bearer"
Content type: application/json.
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.
HTTP 500
internal_error: The operation failed. Retry a read; after a write the change may have happened, so recover as retry by operation describes.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
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.
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
| 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 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
| 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 | |
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
Mailbox or group from the message headers, written by the sender and not verified.
Exactly one of these shapes applies.
Alternative 1
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
name | Yes | string | |
address | Yes | string |
Alternative 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
name | Yes | string | |
group | Yes | array of object |
group fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
name | Yes | string | |
address | Yes | string |
Schema: Mailbox
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
address | Yes | string | Bare address such as 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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
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. |