Search inbound emails
Searches inbound emails with structured filters and optional full-text matching across parsed email fields. This endpoint is optimized for filtered inbox views and CLI polling workflows: callers that only need new accepted mail can pass sort=received_at_asc, snippet=false, include_facets=false, and a date_from timestamp.
q, subject, and body use the same English full-text index as the web inbox search. Structured filters such as from, to, domain_id, status, attachment presence, and spam score bounds are combined with the text query.
Query parameters
Full-text search DSL query.
Filter by sender address or sender domain.
Filter by recipient address or recipient domain.
Full-text search restricted to the subject field.
Full-text search restricted to the parsed text body.
Filter by domain ID.
Filter to inbound emails that are replies to a specific outbound send. The value is a sent_emails.id (UUID). At inbound ingest, Primitive matches the parsed In-Reply-To header (or References as a fallback) against sent_emails.message_id in the same org and records the resolved id on emails.reply_to_sent_email_id. This filter is the strict-threading lookup behind primitive chat and any UI that wants to show the inbound reply to a given send. NULL on inbound that isn't a threaded reply to one of your sends, so existing emails received before this ingestion landed will not match.
Lifecycle status of an INBOUND email (a row in the emails table). Distinct from SentEmailStatus, which describes the OUTBOUND lifecycle (the sent_emails table) and uses a different vocabulary because the lifecycles differ. Possible values:
- pending: the row was inserted at ingestion (mx_main) and has not yet completed the spam / filter / auth pipeline. Body and parsed fields are present; webhook delivery is not yet scheduled. Most rows transition out of pending within seconds.
- accepted: the inbound passed the policy gates and is queued for webhook delivery. The webhook_status field tracks the separate webhook-delivery lifecycle from this point.
- completed: terminal success. Webhook delivery attempted and acknowledged by every active endpoint, OR no endpoints are configured, so the row is durably archived.
- rejected: terminal failure at ingestion (spam, blocked sender, filter rule, malformed). The body and metadata are stored for auditing but no webhook fires and the row is not repliable.
See also webhook_status (separate enum tracking the webhook-delivery state machine) and SentEmailStatus (the outbound vocabulary).
Filter by inbound email lifecycle status.
Filter emails received on or after this timestamp.
Filter emails received on or before this timestamp.
Filter by whether the email has one or more attachments.
Filter to emails with spam score below this value.
Filter to emails with spam score greater than or equal to this value.
Sort mode. Defaults to relevance when a text query is present, otherwise received_at_desc.
Opaque pagination cursor from a previous search response.
Number of results per page
Include subject/body highlight snippets when text search is active.
Include facet counts for sender, domain, status, and attachment presence.
Response
Search results