Cherami Trash API
The trash API from Cherami — 3 operation(s) for trash.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cherami-to:cherami-to-trash-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Cherami To Trash API
version: 1.0.0
contact:
name: Cherami
email: hello@cherami.to
description: 'Operations tagged trash across 2 of this provider''s published API definitions: cherami-to-openapi.json, cherami-to-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://cherami.to
security:
- apiKey: []
tags:
- name: Trash
paths:
/v1/inboxes/{inbox_id}/trash:
get:
operationId: listTrash
tags:
- Trash
summary: List Trash
description: '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:
- name: inbox_id
in: path
required: true
schema:
type: string
description: Cherami resource ID returned by the API.
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: Results per page.
- name: cursor
in: query
required: false
schema:
type: string
description: next_cursor from the previous page. Keep the URL, filters and order unchanged.
responses:
'200':
description: Success.
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
type: object
properties:
messages:
type: array
items:
$ref: '#/components/schemas/TrashEntry'
next_cursor:
anyOf:
- type: string
description: Cursor for the next page, or null at the end. Send it with the same URL, filters and order.
- type: 'null'
required:
- messages
- next_cursor
example:
messages: []
next_cursor: null
'400':
description: '`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.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: '`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).'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
WWW-Authenticate:
schema:
const: Bearer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: '`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.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: '`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.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: '`content_unavailable`: Stored content could not be read. Retry later.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-error-codes:
- unauthorized
- not_found
- invalid_limit
- invalid_cursor
- content_unavailable
- internal_error
servers:
- url: https://cherami.to
/v1/messages/{message_id}/restore:
post:
operationId: restoreMessage
tags:
- Trash
summary: Restore a received message
description: 'Brings a received message back from Trash. Send no request body. It returns to listings, search and its conversation, with its labels and attachments, and repeating a restore is safe.
Restoring every message of a deleted conversation brings the conversation back. After `restorable_until` the message can''t be restored and the request returns `404`.'
parameters:
- name: message_id
in: path
required: true
schema:
type: string
description: Cherami resource ID returned by the API.
responses:
'200':
description: Success.
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Restored'
example:
id: 11111111-1111-4111-8111-111111111111
inbox_id: 11111111-1111-4111-8111-111111111111
thread_id: null
status: restored
message: Example
'401':
description: '`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).'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
WWW-Authenticate:
schema:
const: Bearer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: '`operation_not_allowed`: Sending, or deletion and restore, is turned off for this account; the message says which. Contact hello@cherami.to.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: '`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.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: '`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.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: '`content_unavailable`: Stored content could not be read. Retry later.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-error-codes:
- unauthorized
- not_found
- operation_not_allowed
- content_unavailable
- internal_error
servers:
- url: https://cherami.to
/v1/sent/{message_id}/restore:
post:
operationId: restoreSentMessage
tags:
- Trash
summary: Restore a sent copy
description: Brings a sent copy back from Trash to sent listings, search and its conversation, with its labels. Send no request body. Results and `404` cases are those of restoring a received message.
parameters:
- name: message_id
in: path
required: true
schema:
type: string
description: Cherami resource ID returned by the API.
responses:
'200':
description: Success.
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Restored'
example:
id: 11111111-1111-4111-8111-111111111111
inbox_id: 11111111-1111-4111-8111-111111111111
thread_id: null
status: restored
message: Example
'401':
description: '`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).'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
WWW-Authenticate:
schema:
const: Bearer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: '`operation_not_allowed`: Sending, or deletion and restore, is turned off for this account; the message says which. Contact hello@cherami.to.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: '`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.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: '`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.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: '`content_unavailable`: Stored content could not be read. Retry later.'
headers:
X-Request-ID:
description: Identifies this request; include it when reporting a problem.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-error-codes:
- unauthorized
- not_found
- operation_not_allowed
- content_unavailable
- internal_error
servers:
- url: https://cherami.to
components:
schemas:
Mailbox:
type: object
properties:
address:
type: string
description: 'Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @.'
maxLength: 254
name:
type: string
description: Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters.
x-max-utf8-bytes: 256
required:
- address
additionalProperties: false
ParsedAddress:
oneOf:
- type: object
properties:
name:
type: string
address:
type: string
required:
- name
- address
- type: object
properties:
name:
type: string
group:
type: array
items:
type: object
properties:
name:
type: string
address:
type: string
required:
- name
- address
required:
- name
- group
description: Mailbox or group from the message headers, written by the sender and not verified.
Restored:
type: object
properties:
id:
type: string
description: Cherami resource ID.
inbox_id:
type: string
description: Cherami resource ID.
thread_id:
anyOf:
- type: string
description: Cherami resource ID.
- type: 'null'
status:
type: string
enum:
- restored
- already_live
message:
type: string
required:
- id
- inbox_id
- thread_id
- status
- message
description: 'restored: this request brought the message back. already_live: it wasn''t in Trash and nothing changed. thread_id is its conversation now; null for a received message that isn''t ready.'
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Code to handle. Handle a code you don't recognize by its HTTP status.
message:
type: string
description: Explanation of this case; its wording can change.
required:
- code
- message
required:
- error
TrashEntry:
oneOf:
- type: object
properties:
id:
type: string
description: Cherami resource ID.
kind:
const: received
inbox_id:
type: string
description: Cherami resource ID.
subject:
anyOf:
- type: string
- type: 'null'
from:
anyOf:
- $ref: '#/components/schemas/ParsedAddress'
- type: 'null'
envelope_from:
type: string
description: SMTP sender; can be a bounce address.
deleted_at:
type: string
description: 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:
type: string
description: 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$
required:
- id
- kind
- inbox_id
- subject
- from
- envelope_from
- deleted_at
- restorable_until
- type: object
properties:
id:
type: string
description: Cherami resource ID.
kind:
const: sent
inbox_id:
type: string
description: Cherami resource ID.
subject:
anyOf:
- type: string
- type: 'null'
to:
type: array
items:
$ref: '#/components/schemas/Mailbox'
deleted_at:
type: string
description: 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:
type: string
description: 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$
required:
- id
- kind
- inbox_id
- subject
- to
- deleted_at
- restorable_until
description: A deleted message that can still be restored; kind picks the restore endpoint. from is null for a received message that never became ready.
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: Cherami API key
description: Cherami API key (ch_...), from Account → API keys or from redeeming a human-approved phrase. Every key reaches all of the account's inboxes and mail. MCP OAuth tokens and browser sessions are not accepted.
x-refined-from:
- cherami-to-openapi.json
- cherami-to-openapi.yml