TempInbox API
Disposable mailboxes over HTTP. No account needed to receive mail; an account buys longer-lived mailboxes, your own domains and a developer key.
Get a mailbox and read it
Two calls. The first returns a mailbox and a token scoped to that mailbox only.
curl -sS -X POST https://api.tempinbox.vn/api/v1/mailboxes \
-H 'Content-Type: application/json' \
-d '{"localPart":"my.name"}'
# → { "data": { "id": "…", "address": "my.name@tempinbox.vn", "token": "…", "expiresAt": "…" } }
curl -sS https://api.tempinbox.vn/api/v1/mailboxes/me/messages \
-H "Authorization: Bearer $TOKEN"Omit localPart and the address is generated. It must match
^[a-z0-9][a-z0-9._-]{0,63}$; a taken one answers
mailbox.local_part_taken.
Wait instead of polling
Add ?wait=25 to the messages call and the request is held open until mail arrives
or the timeout passes. Polling in a tight loop is the one thing that will get an IP rate-limited
for no benefit.
curl -sS "https://api.tempinbox.vn/api/v1/mailboxes/me/messages?wait=25" \
-H "Authorization: Bearer $TOKEN"For a one-time code, /mailboxes/me/otp/latest?wait=25 returns the code the
extractor found, so there is no need to parse the mail yourself.
Three kinds of credential
| Token | Gets you | Lives |
|---|---|---|
| mailbox token | one mailbox, its messages and attachments | as long as the mailbox |
guest key tmg_ | the mailboxes one browser session created | 30 min, extended on use |
developer key tm_ | your account's API surface, limited by scope | until revoked |
They are not interchangeable, on purpose: a leaked mailbox token cannot touch an account, and a developer key cannot read a mailbox it does not own.
When something fails
Errors are application/problem+json with a stable code. Branch on the
code, not on the message. Each one has a page: see error codes.
{"type":"…","title":"…","status":401,"code":"auth.invalid_token","traceId":"d8bb5c39"}Limits
Rate limits are per identity, and the response carries Retry-After on
429. Mail volume is capped per day by plan; over it, the sending server gets an SMTP
452 and retries, so mail is deferred rather than lost.