PRprimitive
Sending

List outbound sent emails

Changed on

Returns a paginated list of OUTBOUND emails the caller's org has sent via /send-mail (and /emails/{id}/reply, which forwards through /send-mail). Includes every recorded attempt, including gate-denied attempts that the agent never called and rows still in queued state.

Under an address-bound agent connection credential, the list holds this agent's own sends plus delivered sends from other addresses in the org that name this agent in to, cc or bcc and have matching inbound delivery evidence at this agent. Pass from with the agent's own address to list only its own sends.

For inbound mail received at your verified domains, see /emails. There is no unified send/receive history endpoint; the two surfaces are intentionally separate because the underlying tables, statuses, and lifecycle differ.

Email bodies (body_text, body_html) are NOT included on list rows so a 50-row page can't balloon into a multi-MB response when sends are near the 5MB body cap. Use /sent-emails/{id} to fetch a single row with bodies, or cross-reference by client_idempotency_key if the caller already has the body locally.

get/sent-emails

Request

  • Base URL
    https://api.primitive.dev/v1
  • URL
    https://api.primitive.dev/v1/sent-emails
  • Auth
    HTTP bearer

Query parameters

cursorstring

Pagination cursor from a previous response's meta.cursor field. Format: {ISO-datetime}|{id}

limitinteger

Number of results per page

status'queued' | 'submitted_to_agent' | 'agent_failed' | 'gate_denied' | 'unknown' | 'delivered' | 'bounced' | 'deferred' | 'wait_timeout' | 'scheduled' | 'canceled'

Lifecycle status of a sent_emails row. Possible values:

  • queued: pre-call INSERT; the outbound agent has not yet replied.
  • submitted_to_agent: agent accepted; queue_id is set.
  • agent_failed: agent rejected; error_code and error_message carry the reason.
  • gate_denied: a recipient-scope gate denied the send; the agent was never called. The gates array carries the denial detail. /send-mail returns 403 in this case so callers see the denial synchronously; /sent-emails additionally records the row for historical lookup, which is when this status appears in a listing.
  • unknown: terminal indeterminate; the on-box log poller couldn't classify the receiver's response.
  • delivered / bounced / deferred / wait_timeout: terminal delivery outcomes (see DeliveryStatus).
  • scheduled: created with a future scheduled_at and not yet executed; scheduled_at carries the pending execution time. Reschedulable via PATCH /sent-emails/{id} and cancelable via /sent-emails/{id}/cancel while in this status.
  • canceled: terminal; a scheduled send canceled before execution. canceled_at carries the cancellation time and nothing was dispatched.

Filter to rows in this status. Useful for polling queued rows that haven't transitioned, auditing gate-denied attempts, or listing only successful deliveries.

request_idstring uuid

Filter to the row matching a specific server-issued request_id. The /send-mail response surfaces request_id on every send; this lookup lets the caller find the historical row for a given live call without remembering its id.

idempotency_keystring

Filter to rows with the given client_idempotency_key. Multiple rows can share a key (a retry that hit the idempotent-replay path returns the same row, but a retry with a DIFFERENT canonical payload under the same key is rejected by /send-mail before the row is written, so duplicates are bounded).

date_fromstring date-time

Inclusive lower bound on created_at. An ISO 8601 timestamp with Z or a numeric UTC offset (2026-10-02T00:00:00Z, 2026-10-02T00:00:00-04:00). An offset is read as the instant it names. A time with no zone, or a bare date, is rejected.

date_tostring date-time

Inclusive upper bound on created_at. An ISO 8601 timestamp with Z or a numeric UTC offset (2026-10-02T00:00:00Z, 2026-10-02T00:00:00-04:00). An offset is read as the instant it names. A time with no zone, or a bare date, is rejected.

fromstring email

Exact case-insensitive sender mailbox filter. Returns only sends whose from address equals this value; it is not a substring match, so a partial mailbox matches nothing. Use q to search sender text loosely. Combines with every other filter, and unlike q it is served by every deployment.

includestring
Example:body_text,headers

Extra parts on every row, comma-separated: body_text, body_html, headers, attachments. Reads a page of messages in one request instead of one detail read per row. Parts are withheld where the detail read withholds them. Each body field is cut to 64 KiB per row and a response carries at most 2048 KiB of body text, in page order; a cut or omitted body is named in truncated_fields. Unknown values are a validation_error.

headerstring

Return only sends that set this header: Name=Value matches that exact value, Name alone any value. Name and value compare case-insensitively; the value is trimmed and matched whole, not as a substring, and only the first = separates the two. Matches only the headers the send request set. History pages only: with since or wait it is a validation_error, as is a name that is never stored (trace, signature or credential-like). Sends made before header search was available are not matched.

Response

Page of sent-email summaries

successtrue required

Changes

  • 0360ea8d4f3dRevision changes
    • warning

      added the new agent_changed enum value to the / response property for the response status

    • warning

      added the new agent_changed enum value to the / response property for the response status

    • warning

      added the new agent_changed enum value to the / response property for the response status

    • warning

      added the new agent_limit enum value to the / response property for the response status

    • warning

      added the new agent_limit enum value to the / response property for the response status

    • warning

      added the new agent_limit enum value to the / response property for the response status

    • warning

      added the new already_member enum value to the / response property for the response status

    • warning

      added the new already_member enum value to the / response property for the response status

    • warning

      added the new already_member enum value to the / response property for the response status

    • warning

      added the new directory_limit enum value to the / response property for the response status

    • warning

      added the new directory_limit enum value to the / response property for the response status

    • warning

      added the new directory_limit enum value to the / response property for the response status

    • warning

      added the new invitation_accepted enum value to the / response property for the response status

    • warning

      added the new invitation_accepted enum value to the / response property for the response status

    • warning

      added the new invitation_accepted enum value to the / response property for the response status

    • warning

      added the new invitation_changed enum value to the / response property for the response status

    • warning

      added the new invitation_changed enum value to the / response property for the response status

    • warning

      added the new invitation_changed enum value to the / response property for the response status

    • warning

      added the new invitation_pending enum value to the / response property for the response status

    • warning

      added the new invitation_pending enum value to the / response property for the response status

    • warning

      added the new invitation_pending enum value to the / response property for the response status

    • warning

      added the new invitation_sending enum value to the / response property for the response status

    • warning

      added the new invitation_sending enum value to the / response property for the response status

    • warning

      added the new invitation_sending enum value to the / response property for the response status

    • warning

      added the new invitation_unconfirmed enum value to the / response property for the response status

    • warning

      added the new invitation_unconfirmed enum value to the / response property for the response status

    • warning

      added the new invitation_unconfirmed enum value to the / response property for the response status

    • warning

      added the new invitations_pending enum value to the / response property for the response status

    • warning

      added the new invitations_pending enum value to the / response property for the response status

    • warning

      added the new invitations_pending enum value to the / response property for the response status

    • warning

      added the new member_changed enum value to the / response property for the response status

    • warning

      added the new member_changed enum value to the / response property for the response status

    • warning

      added the new member_changed enum value to the / response property for the response status

    • warning

      added the new project_changed enum value to the / response property for the response status

    • warning

      added the new project_changed enum value to the / response property for the response status

    • warning

      added the new project_changed enum value to the / response property for the response status

    • warning

      added the new recipient_changed enum value to the / response property for the response status

    • warning

      added the new recipient_changed enum value to the / response property for the response status

    • warning

      added the new recipient_changed enum value to the / response property for the response status

  • 5279a7bed7acRevision changes
    • warning

      added the new archive_busy enum value to the / response property for the response status

    • warning

      added the new archive_busy enum value to the / response property for the response status

    • warning

      added the new archive_busy enum value to the / response property for the response status

    • warning

      added the new archive_invalid enum value to the / response property for the response status

    • warning

      added the new archive_invalid enum value to the / response property for the response status

    • warning

      added the new archive_invalid enum value to the / response property for the response status

    • warning

      added the new archive_limit_exceeded enum value to the / response property for the response status

    • warning

      added the new archive_limit_exceeded enum value to the / response property for the response status

    • warning

      added the new archive_limit_exceeded enum value to the / response property for the response status

    • warning

      added the new archive_unsafe_path enum value to the / response property for the response status

    • warning

      added the new archive_unsafe_path enum value to the / response property for the response status

    • warning

      added the new archive_unsafe_path enum value to the / response property for the response status

    • warning

      added the new archive_unsupported enum value to the / response property for the response status

    • warning

      added the new archive_unsupported enum value to the / response property for the response status

    • warning

      added the new archive_unsupported enum value to the / response property for the response status

    • warning

      added the new attachment_name_ambiguous enum value to the / response property for the response status

    • warning

      added the new attachment_name_ambiguous enum value to the / response property for the response status

    • warning

      added the new attachment_name_ambiguous enum value to the / response property for the response status

    • warning

      added the new attachment_not_archive enum value to the / response property for the response status

    • warning

      added the new attachment_not_archive enum value to the / response property for the response status

    • warning

      added the new attachment_not_archive enum value to the / response property for the response status

    • warning

      added the new latest_message_mismatch enum value to the / response property for the response status

    • warning

      added the new latest_message_mismatch enum value to the / response property for the response status

    • warning

      added the new latest_message_mismatch enum value to the / response property for the response status

    • warning

      added the new latest_message_thread_unresolved enum value to the / response property for the response status

    • warning

      added the new latest_message_thread_unresolved enum value to the / response property for the response status

    • warning

      added the new latest_message_thread_unresolved enum value to the / response property for the response status

    • warning

      added the new sent_mail_search_unavailable enum value to the / response property for the response status

    • warning

      added the new sent_mail_search_unavailable enum value to the / response property for the response status

    • warning

      added the new sent_mail_search_unavailable enum value to the / response property for the response status

    • warning

      added the new thread_busy enum value to the / response property for the response status

    • warning

      added the new thread_busy enum value to the / response property for the response status

    • warning

      added the new thread_busy enum value to the / response property for the response status

    • info

      added the new optional query request parameter header

    • info

      added the new optional query request parameter include

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status