List sent messages
GET /v1/inboxes/{inbox_id}/sent
Read as Markdown ↗GET /v1/inboxes/{inbox_id}/sent
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
GET /v1/inboxes/{inbox_id}/sent?limit=20 returns 200 with {"messages":[...],"next_cursor":null}.
Each entry contains sent metadata plus preview, with the same preview contract as received mail. All statuses are listed, newest-submitted first by default. Combine search and filters and choose newest, oldest, or relevance ordering. Limit is 1–100, default 20. Pass next_cursor as a URL-encoded cursor parameter on the same inbox's sent URL. Lists contain bounded previews, not full bodies or attachments. Use labels_all for required tags, optionally combined with labels_any and labels_none; keep the same filters with each cursor. See label filtering.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
inbox_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
limit | query | No | integer | Decimal integer without signs, whitespace or leading zeroes. minimum: 1 maximum: 100 default: 20 |
cursor | query | No | string | Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null. |
query | query | No | string | Nonempty lexical subject/body search, at most 512 UTF-16 code units and 16 words or closed quoted phrases. Every term must match; no raw FTS operators. Attachments and filenames are excluded. |
from | query | No | string | Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope. |
recipient | query | No | string | Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope. |
subject | query | No | string | Case-insensitive literal substring, nonblank and at most 998 UTF-16 code units before trimming. |
after | query | No | string | Inclusive lower service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$ |
before | query | No | string | Exclusive upper service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$ |
labels_all | query | No | array of Label | Require every listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope. maxItems: 32 |
labels_any | query | No | array of Label | Require at least one listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope. maxItems: 32 |
labels_none | query | No | array of Label | Exclude any message carrying a listed label; unlabeled messages qualify. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope. maxItems: 32 |
order | query | No | "newest" or "oldest" or "relevance" | relevance requires query. Listings are live views, not snapshots. default: newest |
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/inboxes/INBOX_ID/sent" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 200
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
messages | Yes | array of SentSummary | |
next_cursor | Yes | string or null |
{
"messages": [],
"next_cursor": null
}HTTP 400
invalid_limit: Use an integer from 1 to 100.
invalid_cursor: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid_draft.
invalid_search: Correct search terms, filters, timestamps, or ordering. See search.
invalid_labels: Correct label names, changes, filter groups, or discovery prefix.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
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.
HTTP 503
outbound_unavailable: Outbound operation failed and a send's outcome may be unknown. Recover using the original key and unchanged payload within its window, or inspect sent messages.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
Schema: Label
1–128 UTF-8 bytes after trimming. Well-formed Unicode without control characters; case-sensitive.
string. x-max-utf8-bytes: 128
Schema: SentSummary
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
inbox_id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
created_at | Yes | string | UTC service instant with milliseconds and Z suffix. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
recipient_count | Yes | integer | minimum: 0 |
status | Yes | "accepted" or "rejected" or "unknown" | |
provider_message_id | Yes | string or null | |
error_code | Yes | string or null | |
thread_id | Yes | string or null | |
in_reply_to | Yes | string or null | |
labels | Yes | array of string | |
preview | Yes | Preview or null |
Schema: Preview
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
text | Yes | string | Beginning of selected text with normalized whitespace; empty is a valid extraction. maxLength: 300 |
truncated | Yes | boolean | |
source | Yes | "reply_text" or "text" or "html" |
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
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 · Download OpenAPI 3.1