List temporary inboxes
The inboxes this credential can see, newest first.
scope defaults to own — only what this credential minted. org
adds the inboxes colleagues have marked org-visible. all asks for
every inbox in the org including private ones; a caller without the
inboxes.manage_all dashboard permission is silently narrowed to
org rather than refused, so asking for more than you may see returns
what you may see.
Unpaginated. An org holds at most 25 live inboxes, limit bounds how
far back the expired ones go, and the standard {data, pagination}
envelope is still returned so this parses like every other collection
here. pagination.has_more is always false.
Message content is never in this response — only counters. Read the
mail at GET /v1/inboxes/{id}/messages.
Query parameters
scope string enum optional Whose inboxes to return. own (default), org, or all. An unknown value is 422, not an empty page.
status string enum optional Narrow to one lifecycle state. Omit for all of them. An unknown value is 422.
account_ref string optional Narrow to the inboxes minted with exactly this account_ref — the partition key you sent at mint. EXACT MATCH, case-sensitive, no trimming: WS_123 does not match ws_123. Combined with scope and status rather than replacing them, so this still only returns what your credential may see. An unknown value is an empty page, not an error, because SendOps does not know which of your keys exist.
limit integer optional Page size (1–200). Default 50.
Responses
Errors follow the RFC 7807 problem format — see the error reference.
data array<object> required Each entry in data:
id string<uuid> required address string required The mailbox to give to whoever is forwarding the mail. Ten opaque characters at the temporary-inbox host. PII in the ordinary sense once it is used: mail sent here is real mail.
expires_at string<date-time> required When the address stops resolving and everything stored against it is deleted. Not extendable.
poll_url string<uri> required The absolute URL of this inbox's long-poll route, on the origin you reached us on. Never assemble it yourself.
pull_url string<uri> optional On the mint response only. A URL on the fetch host that reads
this inbox's mail WITH NO CREDENTIAL — give it to the end user this
inbox is for. Read-only, and whoever holds it reads the mail.
Absent from GET /v1/inboxes/{id} and from the list, because only
the token's hash is stored and there is nothing to return. Lost it?
POST /v1/inboxes/{id}/pull-tokens issues another.
pull_token object optional On the mint response only. The metadata of the pull URL above, so you can revoke it later by id without having kept the URL.
restricted boolean required True when allowed_senders was non-empty and every entry was verified at mint time. A restricted inbox drops mail from anybody else and is exempt from the mint quota and the per-credential cap.
restriction_source string enum | null required WHO vouched for allowed_senders, and it is the difference between a claim SendOps checked and one it took on trust. verified — the minting user held a confirmed claim on every entry, or the org owns the domain. platform — the org asserted the list under Platform mode and SendOps did not verify it. Null when the inbox is not restricted, because then there is no list to vouch for.
One of: verified, platform, null
account_ref string | null required The partition key sent at mint, echoed back exactly as sent — SendOps interprets it in no way. Null when the mint did not carry one. Filter the list by it with ?account_ref=.
Constraints: length 0–128
visibility string enum required private — only the credential that minted it. org — any colleague holding inboxes.use can read the mail. Others get 404, never 403.
One of: private, org
label string required A human note, 80 characters at most. Matched against nothing.
status string enum required expired — the cleanup job retired it; the messages route answers 410. deleted — the owner purged it early; the messages route answers 404.
One of: active, expired, deleted
allowed_senders array<string> required Frozen at mint. Each entry is a full address the minting user had verified, or @example.com for a domain the org owns. Revoking a verified sender later does not change this list. Empty means the inbox accepts mail from anyone, which is what makes it metered.
message_count integer required Messages delivered to this inbox.
dropped_count integer required Messages turned away — a sender not on allowed_senders, or a virus verdict. Nothing is bounced, so a sender is never told. A rising dropped_count with a flat message_count is the signature of a forward from the wrong address.
created_at string<date-time> required pagination object required Fields of pagination:
has_more boolean required next_cursor string | null optional validation_failed Problem. When the refusal is about a
reference — a segment key, template slug, topic or attribute name the
organization does not have — it additionally carries validation_code,
field, line/column, missing, candidates and next_step, so a
client can correct the call without a second round of guessing. See
ValidationProblem.
application/problem+json code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json