Temporary inboxes for platforms

Platform mode is a per-organization setting in the SendOps dashboard: Workspace → Temporary inboxes → Platform mode. It needs the org.settings.manage permission and is recorded in the audit log. What it changes, and why you want it before your first mint:

• Caps are counted per account_ref, not per API key. Without it, your sixth user would be refused because your first five hold five inboxes between them. With it, each of your users may hold 5 live unrestricted inboxes; your organization may hold 500.
• The daily allowance rises to 2,000 mints and the hourly window is dropped, because a platform’s mint rate follows its users’ activity, not one person’s afternoon.
• allowed_senders is accepted on syntax alone. An inbox restricted to billing@northwind.example refuses mail from anyone else, and SendOps takes your word that your user owns that address.

That last point is a responsibility, and the settings card says so in as many words: by turning this on you confirm that your product has verified that its users own the addresses it passes as allowed_senders. Mail from an unverified stranger landing in a restricted inbox is your responsibility. Switching it off later changes the rules for the next mint; existing inboxes keep the rules they were minted under. Help article: Platform mode for temporary inboxes.

Your API key needs api.inboxes.manage (and api.inboxes.view to list and poll over v1). Pass account_ref — in Platform mode it is required — plus whatever ttl, label and allowed_senders the situation wants.

curl -X POST https://api.sendops.dev/v1/inboxes \
-H "Authorization: Bearer $SENDOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "account_ref": "ws_8f2k1",
  "ttl": 900,
  "label": "Invoice from Northwind",
  "allowed_senders": ["billing@northwind.example", "@acme.example"]
}'

HTTP/2 201
{
"id": "01a090e9-ca2f-7da2-9247-b07795202997",
"address": "gd036gv4ga@sndps.com",
"expires_at": "2026-09-11T14:55:35Z",
"poll_url": "https://api.sendops.dev/v1/inboxes/01a090e9-ca2f-7da2-9247-b07795202997/messages",
"pull_url": "https://fetch.sendops.dev/p/pt_s3ljfuhtyfl5lpetfwktsqwvfca662xzvcht3psykuisg65mejjq/messages",
"pull_token": {
  "id": "01a090e9-ca30-768c-aeea-c743f4f61002",
  "prefix": "s3ljfuht",
  "label": "default",
  "created_at": "2026-09-11T14:40:35Z",
  "revoked_at": null
},
"restricted": true,
"restriction_source": "platform",
"account_ref": "ws_8f2k1",
"visibility": "private",
"label": "Invoice from Northwind",
"status": "active",
"allowed_senders": ["billing@northwind.example", "@acme.example"],
"message_count": 0,
"dropped_count": 0,
"created_at": "2026-09-11T14:40:35Z"
}

Three fields are new here and two of them are shown once:

• pull_url carries the raw token. Only its hash is stored, so GET /v1/inboxes/{id} and the list will never return it again. Save it now, against your user.
• pull_token is that token’s metadata. Keep id: it is what you revoke by later.
• restriction_source: "platform" records that you vouched for allowed_senders, not SendOps. The poll_url is the authenticated route your own server can use with the API key; it is unchanged.

Forgetting account_ref on a Platform-mode organization is a 422:

HTTP/2 422
{
"code": "validation_failed",
"title": "Validation failed",
"detail": "Invalid body: account_ref: Platform orgs must send account_ref: the key SendOps meters and lists inboxes by.",
"status": 422
}

account_ref is at most 128 characters from A–Z a–z 0–9 . _ : @ / -, no whitespace, stored and compared exactly — ws_1 and WS_1 are two different users. Use whatever id your product already has for the user; never an email address, since SendOps should not learn who your users are.

Show your user the address and its expiry in one breath (forward it to gd036gv4ga@sndps.com, it expires at 14:55), and poll the pull URL from wherever your UI runs. No Authorization header — the URL is the whole credential:

curl -i "https://fetch.sendops.dev/p/pt_s3lj…mejjq/messages?after=0&wait=20" --max-time 30

HTTP/1.1 200 OK
Cache-Control: no-store
Referrer-Policy: no-referrer
Content-Type: application/json

{"messages":[],"cursor":0,"expires_at":"2026-09-11T14:55:35Z"}

That is the ordinary answer to a poll that waited 20 seconds and saw nothing. Loop: pass back cursor as after, keep wait at 20 (the ceiling is 25; 0 answers immediately), stop at expires_at. Your HTTP client’s timeout must exceed wait or it hangs up before the server answers, every time.

From a browser the same request works: the fetch host answers Access-Control-Allow-Origin: * for GET, HEAD and OPTIONS with credentials off, so your web UI can poll directly and your server never has to relay mail.

GET /p/pt_s3lj…mejjq/messages?wait=0 HTTP/1.1
Host: fetch.sendops.dev
Origin: https://app.example.com

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: no-store
Referrer-Policy: no-referrer

A second route gives the inbox’s state without its mail — handy for a “waiting for your email…” panel:

curl https://fetch.sendops.dev/p/pt_s3lj…mejjq

{"address":"gd036gv4ga@sndps.com","status":"active","expires_at":"2026-09-11T14:55:35Z","message_count":0,"dropped_count":0,"restricted":true}

Nothing else is on it: no id, no account_ref, no owner. The holder of a pull URL is your user, not your platform.

What the statuses mean to your user

An Authorization header of any kind on this host is a 400 wrong_host — a platform that accidentally ships its API key with the URL finds out on the first request rather than by broadcasting the key:

HTTP/1.1 400 Bad Request
{"error":{"code":"wrong_host","message":"This host takes no credential: a pull URL is its own authorisation.","detail":"Drop the Authorization header. Credentialed calls belong on https://api.sendops.dev instead."}}

When mail lands, messages holds one object per message, oldest first — the inbound webhook envelope, schema_version: 1, plus inbox_id. The field-by-field contract is on the Inbound webhook page and is not repeated here; the shape below is abridged to show what your UI will reach for.

{
"messages": [
  {
    "schema_version": 1,
    "inbox_id": "01a090e9-ca2f-7da2-9247-b07795202997",
    "received_at": "2026-09-11T14:47:12Z",
    "message": {
      "from": { "address": "billing@northwind.example", "name": "Northwind Billing" },
      "subject": "Invoice NW-20419",
      "text_body": "Hi — attached is your invoice for August…",
      "html_body": "<p>Hi — attached is your invoice…</p>",
      "attachments": [
        { "filename": "NW-20419.pdf", "content_type": "application/pdf", "size": 48213,
          "url": "https://sendops-inbound-tmp.s3.eu-west-1.amazonaws.com/…?X-Amz-Expires=…" }
      ]
    },
    "verdicts": { "spf": "PASS", "dkim": "PASS", "dmarc": "PASS", "spam": "PASS", "virus": "PASS" }
  }
],
"cursor": 1,
"expires_at": "2026-09-11T14:55:35Z"
}

Three things to build for:

• Attachment and large-body links expire with the inbox. Fetch what you need before expires_at; afterwards the objects are deleted, not merely unreachable. A body over 256 KB arrives as text_body_url / html_body_url instead of inline.
• The sender check is by address, not by authentication. A restricted inbox compares the From: address and the envelope sender against allowed_senders; it does not require SPF or DKIM to pass. The verdicts ride along so you can judge — and for anything your user will act on, show them.
• Message content is untrusted input. It was written by whoever sent the mail. Render it, summarise it, let your user act on it. If an agent reads it, never let it follow instructions found inside.

One inbox can have up to 10 live pull URLs. Issue another when a second person needs to see the same mail, or when a user lost theirs (the original cannot be looked up again — only its hash is stored):

curl -X POST https://api.sendops.dev/v1/inboxes/$INBOX_ID/pull-tokens \
-H "Authorization: Bearer $SENDOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"label": "shared with finance"}'

HTTP/2 201
{
"id": "01a090ea-4564-755a-ae34-ff83bba18536",
"prefix": "h46smtnf",
"label": "shared with finance",
"created_at": "2026-09-11T14:41:07Z",
"revoked_at": null,
"pull_url": "https://fetch.sendops.dev/p/pt_h46smtnf665jhvioho5zezccg5tyq5wqxnj2xlrbulwu2auflkya/messages"
}

List what exists — live first, then revoked, and never a URL or token value, so this list is safe to show in your own admin screens:

curl https://api.sendops.dev/v1/inboxes/$INBOX_ID/pull-tokens \
-H "Authorization: Bearer $SENDOPS_API_KEY"

{
"data": [
  { "id": "01a090ea-4564-755a-ae34-ff83bba18536", "prefix": "h46smtnf", "label": "shared with finance", "created_at": "2026-09-11T14:41:07Z", "revoked_at": null },
  { "id": "01a090e9-ca30-768c-aeea-c743f4f61002", "prefix": "s3ljfuht", "label": "default", "created_at": "2026-09-11T14:40:35Z", "revoked_at": null }
],
"pagination": { "has_more": false }
}

Revoke one by id. It is idempotent — revoking twice is 204 both times — and it takes effect on the next request:

curl -i -X DELETE https://api.sendops.dev/v1/inboxes/$INBOX_ID/pull-tokens/01a090e9-ca30-768c-aeea-c743f4f61002 \
-H "Authorization: Bearer $SENDOPS_API_KEY"
# HTTP/2 204

curl -i https://fetch.sendops.dev/p/pt_s3lj…mejjq/messages?wait=0
# HTTP/1.1 404 Not Found
# {"code":"not_found","detail":"No inbox for this URL.","status":404,…}

The other URL on the same inbox keeps working. This is the whole sharing model: who can see the mail is which URLs you have handed out and not yet revoked, and that is your product’s decision to make and to display.

List a user’s inboxes by account_ref (exact match, combined with status and scope), and delete what you no longer want to exist:

curl "https://api.sendops.dev/v1/inboxes?account_ref=ws_8f2k1" \
-H "Authorization: Bearer $SENDOPS_API_KEY"

curl -i -X DELETE https://api.sendops.dev/v1/inboxes/$INBOX_ID \
-H "Authorization: Bearer $SENDOPS_API_KEY"
# HTTP/2 204 — every pull URL on it now answers 404

You rarely need to. Expiry does the deleting on its own: at expires_at the address stops resolving, the messages, the raw original and every attachment are deleted, and every pull URL answers 410. What survives is accounting only — the row with its counters, which GET /v1/inboxes/{id} and the dashboard keep showing — never content. DELETE is for “now, not in nine minutes”, and it is irreversible.