cherami.
API referenceReceived messages

Count received messages

GET /v1/inboxes/{inbox_id}/messages/count

Read as Markdown ↗

GET /v1/inboxes/{inbox_id}/messages/count

Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.

Counts received messages matching the same query and filters as List received messages, including messages that aren't ready to read yet.

Parameters

ParameterLocationRequiredTypeMeaning
inbox_idpathYesstringCherami resource ID returned by the API.
queryqueryNostringWords or "quoted phrases" to find in the subject and body; every term must match. At most 16 terms and 512 UTF-16 code units. OR, NOT and wildcards have no special meaning, and attachments aren't searched. See Find mail.
fromqueryNostringBare sender address from the message headers, matched exactly without regard to case; not the SMTP envelope. At most 320 UTF-16 code units.
recipientqueryNostringBare recipient address from the message headers, matched exactly without regard to case; not the SMTP envelope. At most 320 UTF-16 code units.
subjectqueryNostringText the subject contains, matched literally without regard to case. At most 998 UTF-16 code units.
afterqueryNostringEarliest (inclusive) receipt or send time, as an ISO 8601 instant with a timezone, such as 2026-10-01T00:00:00Z. after must be earlier than before. URL-encode it, including any + in an offset. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$
beforequeryNostringLatest (exclusive) receipt or send time, as an ISO 8601 instant with a timezone, such as 2026-10-01T00:00:00Z. after must be earlier than before. URL-encode it, including any + in an offset. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$
labels_allqueryNoarray of LabelMessages carrying every listed label. Repeat the parameter for each label rather than separating with commas. The three label groups combine with AND. maxItems: 32
labels_anyqueryNoarray of LabelMessages carrying at least one listed label. Repeat the parameter for each label rather than separating with commas. The three label groups combine with AND. maxItems: 32
labels_nonequeryNoarray of LabelMessages carrying none of the listed labels, unlabeled ones included. Repeat the parameter for each label rather than separating with commas. The three label groups combine with AND. maxItems: 32

curl example

Supply CHERAMI_API_KEY privately.

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

Success.

  • X-Request-ID: Identifies this request; include it when reporting a problem.

Content type: application/json.

FieldRequiredTypeMeaning and constraints
countYesintegerminimum: 0
{
  "count": 0
}

HTTP 400

invalid_search: Correct the search terms, filters, timestamps or ordering the message names. See search.

invalid_labels: Correct the label name, label change, filter group or discovery prefix the message names.

  • X-Request-ID: Identifies this request; include it when reporting a problem.

Content type: application/json.

Error

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.

Error

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

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.

Error

Schema: Label

1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.

string. x-max-utf8-bytes: 128

Schema: Error

FieldRequiredTypeMeaning and constraints
errorYesobject

error fields

FieldRequiredTypeMeaning and constraints
codeYesstringCode to handle. Handle a code you don't recognize by its HTTP status.
messageYesstringExplanation of this case; its wording can change.

Errors, limits and pagination · Download OpenAPI 3.1

On this page