A mailbox is an email address your agent owns — it receives mail, sends mail, and runs automations. Every agent gets one at registration (a readable address like swift-otter@tinysend.com). You can create more.

Create a mailbox

POST https://api.tinysend.com/v1/mailboxes
Authorization: Bearer sk_...

{ "name": "support", "address": "support@yourdomain.com" }

Types: persistent (default), disposable, proxy.

Disposable mailboxes

For one-off signups and verification flows. Omit address and a readable one is auto-generated on tinysend.com:

POST /v1/mailboxes
{ "type": "disposable", "ttl": "1h", "name": "signup-acme" }

ttl — lifetime as a duration shorthand ("1h", "24h", "7d") or a number of seconds. max 30 days, default 24h
expires_at — ISO 8601 timestamp, alternative to ttl
domain — domain for the auto-generated address, defaults to tinysend.com

The response includes the address to use and the mailbox id.

Read messages

GET /v1/mailboxes/:id/emails?direction=inbound
GET /v1/mailboxes/:id/emails/:emailId

List filters: direction (inbound/outbound), status (received/read/replied/archived/failed), source_tag, cursor, limit. The detail response includes the full message plus extracted_data and handler_results when automations have run.

Plus-addressing and source tags

Mail sent to address+anything@domain is delivered to the base mailbox, so you can hand out variants like swift-otter+github@tinysend.com without creating new mailboxes. Messages also carry an optional source_tag field — filter the list endpoint with ?source_tag=... when it’s set.

Send and reply

POST /v1/mailboxes/:id/emails
{ "to_address": "someone@example.com", "subject": "Re: your question", "text_body": "...", "in_reply_to": "<message-id>" }

text_body is required, html_body optional. Pass in_reply_to (the message-id of the inbound email) to keep threading.

Recipe: receive an OTP code

The full flow for signing up for a third-party service and reading the verification code:

create a disposable inbox:

POST /v1/mailboxes
{ "type": "disposable", "ttl": "1h", "name": "acme-signup" }

enable the otp automation on it:

POST /v1/automations
{ "type": "otp", "entity_type": "mailbox", "entity_id": "<mailbox id>" }

use the mailbox address to sign up for the service
poll for the inbound email and the extracted code:

GET /v1/mailboxes/:id/emails?direction=inbound      → take the first message id
GET /v1/mailboxes/:id/emails/:emailId               → read extracted_data.otp

Poll every few seconds; delivery plus extraction typically completes well within a minute. When extracted_data.otp is present, that’s your code.

Questions?

Contact us at hi@tinysend.com.

Agent mailboxes — tinysend agents