Count received messages
GET /v1/inboxes/{inbox_id}/messages/count
Read as Markdown ↗GET /v1/inboxes/{inbox_id}/messages/count
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
GET /v1/inboxes/{inbox_id}/messages/count returns 200 with {"count":3}.
The same search and filters as the received list apply, including combined and exclusion filters. This is the current count, including unfinished messages, not an unread count or a snapshot shared with pagination.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
inbox_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
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 |
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/messages/count" \
--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 |
|---|---|---|---|
count | Yes | integer | minimum: 0 |
{
"count": 0
}HTTP 400
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 500
internal_error: Operation failed; a write may already have happened. Follow the operation-specific recovery below.
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: 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