Temporary inboxes

A temporary inbox is a receiving address that exists for minutes. You mint one, hand out the address, long-poll for what arrives, and at expires_at the address stops resolving and everything it received is deleted: the parsed messages, the raw original, every staged attachment.

It exists for one shape of problem. Somebody is describing an email to you rather than showing it to you, or an agent needs to read a one-time code, a receipt, a bounce notification. Copy and paste is the alternative and it loses the headers, mangles the encoding, drops the attachments, and cannot answer a question about authentication at all.

Building this into your own product for your users? Read Temporary inboxes for platforms first: it covers Platform mode, account_ref, and the credential-free pull URL every mint now returns. This page is the full reference.

Addresses are minted at sndps.com, a receiving domain SendOps owns. It publishes no sending policy other than a refusal (v=spf1 -all, p=reject), because nothing ever sends from it.

What a temporary inbox is not

• Not a mailbox. The ceiling on ttl is one hour. A promise measured in hours invites the address to be used as somewhere mail lives, which is a different product with a different privacy story.
• Not in your AWS account. Inbound Email is the customer-owned surface: your subdomain, your MX, your bucket, your endpoint, delivering indefinitely. A temporary inbox is on SendOps infrastructure and lives for minutes. The parsed payload is the same; the lifetime and the ownership are not.
• Not a signup address. Restricted inboxes exist so this one cannot be used to collect a stranger’s confirmation email, and the mint quota exists to make the unrestricted case unattractive at volume.
• It never sends. No bounces, no non-delivery reports, no auto-replies, for any rejection reason. Mail that fails the sender check or the virus scan is dropped and counted, and the sender is never told.

Scopes

DELETE /v1/inboxes/{id} is classified destructive, so a test-environment credential (sk_test_ / oc_test_) is refused it with test_environment_forbidden. Minting and editing are not: an inbox expires on its own, so a test credential may create one.

The endpoints

Sender verification has its own page. Full request and response schemas for everything above are in the sidebar under Inboxes.

Lifecycle

Mint. POST /v1/inboxes returns the address, the expiry, and — in this response only — pull_url, a URL on fetch.sendops.dev that reads the inbox with no credential, plus pull_token, its revocable handle. account_ref is your own opaque key for the user the inbox is for; optional here, required in Platform mode. It returns the address and the expiry immediately. ttl is 60 to 3600 seconds and defaults to 600. label is a human note of at most 80 characters, matched against nothing. visibility is private (the default: only the credential that minted it) or org (any colleague holding the inboxes.use dashboard permission can read the mail).

Forward. Give out address with its expiry. An address handed over without one is an address somebody tries to use tomorrow.

Poll. Long-poll poll_url, which comes back on the inbox and should never be assembled by hand.

Expiry and purge. At expires_at the address stops resolving, the messages leave Redis, and the raw objects and staged attachments leave S3. There is no backup behind any of it. DELETE /v1/inboxes/{id} does the same thing early, before the response returns.

Worked example: forward one email to an agent

Two calls. Mint, then loop.

curl -X POST https://api.sendops.dev/v1/inboxes \
-H "Authorization: Bearer $SENDOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttl": 600, "label": "Northwind receipt"}'

{
"id": "0192c0a4-…",
"address": "k7q2m9xv4p@sndps.com",
"expires_at": "2026-09-10T14:32:00Z",
"poll_url": "https://api.sendops.dev/v1/inboxes/0192c0a4-…/messages",
"restricted": false,
"visibility": "private",
"label": "Northwind receipt",
"status": "active",
"allowed_senders": [],
"message_count": 0,
"dropped_count": 0,
"created_at": "2026-09-10T14:22:00Z"
}

Tell the user in one breath: forward it to k7q2m9xv4p@sndps.com, it expires at 14:32. Then poll, passing back the cursor each time:

curl "https://api.sendops.dev/v1/inboxes/$INBOX_ID/messages?wait=20&after=$CURSOR" \
--max-time 30 \
-H "Authorization: Bearer $SENDOPS_API_KEY"

{
"messages": [ /* one inbound-webhook payload each, plus inbox_id */ ],
"cursor": 1,
"expires_at": "2026-09-10T14:32:00Z"
}

An empty messages array is the ordinary answer to a poll that waited and saw nothing. It is not an error. Poll again with the cursor you were given, and stop at expires_at.

Worked example: receive a one-time code from your own system

When the mail is coming from something you run, verify that sender once and the inbox becomes restricted, which takes it out of the mint quota entirely.

curl -X POST https://api.sendops.dev/v1/verified-senders \
-H "Authorization: Bearer $SENDOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "noreply@acme.com"}'

curl -X POST https://api.sendops.dev/v1/verified-senders/$CLAIM_ID/confirm \
-H "Authorization: Bearer $SENDOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"code": "418293"}'

That round trip is a one-off, and it needs a credential that identifies a person, an API key or a user-delegated token, because a claim is one person’s proof that they can read one mailbox; a client-credentials token is refused. See Verified senders for the whole flow. Now every mint against that address is unmetered:

curl -X POST https://api.sendops.dev/v1/inboxes \
-H "Authorization: Bearer $SENDOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttl": 300, "label": "login OTP", "allowed_senders": ["noreply@acme.com"]}'

The response comes back with restricted: true. Point your signup or login flow at address, poll for the message, and read the code out of message.text_body.

An entry in allowed_senders is either a full address you have verified, or @acme.com for a domain your organization has verified in SendOps. (In Platform mode the entries are checked for syntax only and the inbox records restriction_source: "platform"; outside it, restriction_source is "verified".) An entry that is neither is a 422 naming it, never a silently dropped entry: an allow list that lost an entry would be an inbox that quietly stopped being restricted.

Quotas, caps, and why restricted inboxes are unrationed

Metering applies only to unrestricted inboxes, and for an ordinary organization it is keyed on whether the org has connected its own AWS account, not on plan. An organization in Platform mode has a different table — no hourly window, 2,000 mints a day, 5 live unrestricted inboxes per account_ref, 500 live per organization — described in Temporary inboxes for platforms.

Two ceilings on live inboxes apply on top:

• 5 per credential, counting unrestricted inboxes only. The credential is the API key, the OAuth client, or the person behind a user-delegated token.
• 25 per org, counting restricted inboxes too. This one is not an abuse control: it bounds one tenant’s footprint on a shared receiving pipe, and the pipe does not care why a message arrived.

A restricted inbox skips both the mint quota and the per-credential cap because it cannot be used for the thing the quota is defending against. Mail from anyone not on the list is dropped, so it can never receive a stranger’s signup confirmation. Verifying one address is the difference between three inboxes a day and an unmetered supply.

The 429 reasons

A refused mint is a 429 whose reason extension says which limit, so a client can tell “wait an hour” from “verify a sender” from “an administrator switched this off”.

Long-polling

GET /v1/inboxes/{id}/messages takes two query parameters and both matter.

• wait is 0 to 25 seconds. 0, the default, answers immediately with whatever is there. Out of range is a 422 rather than a clamp: a wait silently shortened is indistinguishable from mail that never arrived. The hold also stops at expires_at, whichever comes first.
• after is the cursor from your previous response. It is the number of messages you have seen so far, an integer rather than an opaque token on purpose: if you lose it, send 0 and you get the whole inbox back rather than an error.

Every poll costs one request against your rate-limit budget, counted on entry and not refunded for the time spent waiting. A 20-second loop is 3 requests a minute, which is nothing for a live key. A test key’s budget can be as low as 1 a minute, which makes a tight loop unusable from a test credential: use a live key, or poll less often. See Rate Limiting.

Responses on this route are always Cache-Control: no-store. They are somebody’s messages.

The payload

Each message is the same object the inbound webhook POSTs, schema_version: 1, with inbox_id added. An agent written against one reads the other without a second parser, so prototyping against a temporary inbox is prototyping against production inbound.

The field-by-field description lives on the Inbound webhook page, and that document is the source if the two ever read differently. Two things are specific to this surface:

• inbox_id is present here and absent from the webhook. It is the inbox the message was delivered to.
• Presigned URLs expire with the inbox. raw_url, message.attachments[].url, message.text_body_url and message.html_body_url are signed for whatever is left of the inbox’s life and are minted fresh on every response. Fetch what you need before expires_at. Afterwards the objects are deleted, not merely unreachable.

Bodies may also arrive out of line: a body over 256 KB is stored as an object, and text_body or html_body is empty with text_body_url or html_body_url set instead. Handle both.

Reading what arrives

The sender check is by address only. A restricted inbox compares the From: header address and the SES envelope sender against allowed_senders, and either matching passes. It is not an authentication check: SPF and DKIM can be forged by anyone controlling the headers. verdicts.spf, verdicts.dkim and verdicts.dmarc ride along with every message precisely so you can judge that yourself. Treat the address as a filter and the verdicts as the evidence.

Spam and virus are not treated alike. Mail that fails the spam scan is delivered, with the verdict in the payload. Transactional mail forwarded through a consumer mailbox trips spam heuristics readily, and the agent waiting for a one-time code is better placed to judge than we are. Mail that fails the virus scan is dropped and never appears. So the message list is not a complete record of everything sent to the address.

An empty result is never proof nobody sent anything. On a restricted inbox a forward from the user’s other account is discarded with no bounce, and from your side that looks identical to a user who has not got round to it. dropped_count on the inbox is the tell: non-zero with a flat message_count means something arrived and was refused. Tell them to forward from the address they verified. The list is frozen at mint, so verifying that sender now does not rescue this inbox: mint a new one.

After expiry

GET /v1/inboxes/{id} keeps answering for an expired inbox, deliberately: the row is accounting and outlives the content, so “did anything arrive before it lapsed” stays answerable. Only the messages go away.

A private inbox belonging to a colleague is a 404 rather than a 403 everywhere on this surface, because a 403 would confirm the id exists. DELETE on an already-deleted inbox is also 404: if you want “make sure it is gone”, treat 204 and 404 as the same outcome.

Availability

Temporary inboxes are enabled for every organization. The feature keeps a kill switch: if it is ever turned off for yours, every route on this page answers 404, in the RFC 7807 problem shape every other error here uses — that is the gate, not a missing id.

Related

• Temporary inboxes for platforms: building this into your own product — Platform mode, account_ref, pull URLs
• Verified senders: the code round trip that makes an inbox restricted
• Inbound webhook: the payload, field by field
• Inbound Email: receiving at your own domain, in your own AWS account, indefinitely
• Rate Limiting: the budget each poll spends
• Errors: the problem document every refusal here returns