Change an inbox's label or visibility
Two fields, and the omissions are the contract.
ttl and expires_at are not settable. An expiry that could be
pushed out would make "and then it is gone" a negotiation. Mint another
inbox instead.
allowed_senders is not settable. The list is frozen at mint,
because restricted is a claim about what was verified at that moment
— an inbox that could gain senders later could be un-restricted after
it had already skipped the quota.
Flipping visibility to org is a disclosure, not a setting: it
exposes the mail this inbox has received to every colleague holding
inboxes.use. Flipping back removes their access to anything they
have not already read.
A body naming neither field is 422, not a no-op 200.
Path parameters
id string<uuid> required The inbox's UUID, exactly as returned by POST /v1/inboxes. A value that is not a UUID is a 404 rather than a 422 — it names nothing, and saying "that is not a valid UUID" would confirm the format of ids that do exist.
Request body
Content type: application/json
visibility string enum optional Flipping to org DISCLOSES this inbox's mail to every colleague holding inboxes.use.
One of: private, org
label string optional Constraints: length 0–80
Responses
Errors follow the RFC 7807 problem format — see the error reference.
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 code: invalid_scope), or it is bound to the test environment and this operation is irreversible (code: test_environment_forbidden). Branch on code: the first is fixed by granting the scope, the second only by using a live credential. See the "Live and test credentials" section of the API description. application/problem+json 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