Send a message from an org inbox
POST /v1/admin/orgs/{org_id}/projects/{project_id}/inboxes/{addr}/send
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The full inbox address, URL-encoded (e.g. agent7%40extrovertmail.com).
Request Body required
Section titled “Request Body required ”At most 50 combined To/Cc/Bcc recipients and 1,800,000 encoded message bytes including headers and attachments. Size violations return HTTP 413; recipient/count violations return HTTP 400. Applies before review acceptance and after edits.
object
Plain-text body. This is the canonical name and matches ReplyRequest.text, ForwardRequest.text and Message.text.
DEPRECATED alias for text, kept accepted indefinitely so already-deployed callers keep working; it will never be removed. Send text in new code. Supplying BOTH with different content is a 400 (code bad_request, errors[].code conflicting_alias); the server never guesses which bytes to relay; supplying both with identical content is accepted.
Optional HTML body
Override the Reply-To header.
Arbitrary custom headers (reserved/unsafe header names are dropped).
object
New API sends with a reply header are rejected with reply_workflow_required (422). Read the full thread and use the reply endpoint with expected_context_version. Existing queued messages retain their original delivery semantics.
An outbound attachment on send/reply/forward.
object
Standard base64-encoded attachment bytes. Up to 20 attachments share the 1,800,000-byte encoded email limit with headers and both bodies.
Review Loop (HITL) per-send assertion. review (default) routes the message into the human-review queue; direct requests an immediate send. The authoritative account/inbox review policy may downgrade direct to review. Setting any of mode/intent/category_id opts the send into the Review Loop.
The agent’s “for the human reviewer” summary. summary is REQUIRED when the resolved mode is review (else the submit is 422).
object
Free-text intent summary (who/what/why).
Structured intent payload.
object
Opaque category id (cat_…) matched from the registry. Never a name.
Agent-supplied confidence (0..1) in the category match. Feeds the submit-time min_confidence auto-send gate ONLY; the server never scores ($0 LLM). Below the effective threshold (or omitted when a threshold is set) the would-be auto-send routes to needs_review (gate_outcome held:low_confidence).
Opaque token from a fresh, unfiltered GET /v1/rules for this agent, project, and category.
DEPRECATED body-level alias for the Idempotency-Key header, tolerated for @extrovert.dev/sdk <= 0.1.0 builds that serialize the whole request object. Send the header instead; when both are present the header wins. Note that the replay key is scoped to a hash of the RAW request body, so the same logical message retried once as body and once as text under one key is a body mismatch and answers 409 idempotency_conflict. Different bytes are a different request.
Responses
Section titled “ Responses ”Accepted for delivery.
object
Whether the accepted message has a resolvable saved Sent copy. Archive failure never resends mail.
Per-recipient counts by transport state. Absent states have count zero.
object
A stable identifier for the submitted message the sender can self-correlate on: the opaque msg_ id when the Sent append resolved, else the bracketed RFC5322 Message-ID header value. Present on the direct-send response; always non-empty when status is “sent”.
Opaque review id (rr_…) for the review row that governed this send. ADDITIVE; see SendResult.review_id.
Invalid request.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMachine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.
Consumed plus reserved units.
Requested additional units.
Next UTC usage-period boundary; pending reservations survive this boundary.
Missing or invalid credential.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMachine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.
Consumed plus reserved units.
Requested additional units.
Next UTC usage-period boundary; pending reservations survive this boundary.
Resource not found.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMachine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.
Consumed plus reserved units.
Requested additional units.
Next UTC usage-period boundary; pending reservations survive this boundary.