{"openapi":"3.1.0","info":{"title":"receivemail.dev API","version":"1.0.0","summary":"Disposable email inboxes for tests, one API call, no signup.","description":"Create a throwaway email address, trigger your app's verification email to it, then read or long-poll what arrives. Free without an API key; paid plans (Pro $7/mo, Pro + Webhooks $19/mo) add 24h mailboxes, higher limits, an extracted `otp` field and signed webhooks. Plain-text bodies only (no HTML or attachments); mail is kept about 24h. Rate limits: free 20 creates/min per IP and 5,000/day shared; paid 120 creates/min per key.","contact":{"name":"receivemail.dev","email":"flovoice53@gmail.com","url":"https://receivemail.dev/"},"termsOfService":"https://receivemail.dev/faq","license":{"name":"MIT","identifier":"MIT"}},"servers":[{"url":"https://receivemail.dev"}],"externalDocs":{"description":"Developer portal","url":"https://receivemail.dev/developers"},"tags":[{"name":"mailboxes","description":"Create disposable mailboxes and read their messages."}],"paths":{"/mailboxes":{"post":{"operationId":"createMailbox","tags":["mailboxes"],"summary":"Create a disposable mailbox","description":"Returns a random address and its secret. No authentication needed on the free tier. Send `Authorization: Bearer rmk_…` (a paid API key) for 24h mailboxes, per-key limits and webhooks. The secret is returned only here; keep it to read the mailbox.","security":[{},{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","minimum":1,"maximum":1440,"default":15,"description":"Mailbox lifetime. Free tier is capped at 60, paid keys at 1440."},"webhookUrl":{"type":"string","format":"uri","description":"Pro + Webhooks only: public https URL that receives each email as signed JSON."}}},"example":{"ttlMinutes":15}}}},"responses":{"201":{"description":"Mailbox created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mailbox"},"example":{"address":"a1b2c3d4e5f6@receivemail.dev","expiresAt":"2026-11-02T10:15:00.000Z","secret":"3f9c…"}}}},"400":{"description":"Invalid webhookUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key presented but invalid or inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"webhookUrl needs the Pro + Webhooks plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (free: 20/min per IP or the shared daily limit; paid: 120/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mailboxes/{address}":{"get":{"operationId":"getMailbox","tags":["mailboxes"],"summary":"Get mailbox metadata","security":[{"mailboxSecret":[]}],"parameters":[{"name":"address","in":"path","required":true,"description":"The full address returned by POST /mailboxes, e.g. a1b2c3d4e5f6@receivemail.dev (URL-encode the @ if your client needs it).","schema":{"type":"string"}}],"responses":{"200":{"description":"Mailbox metadata","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Missing or wrong mailbox secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Mailbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mailboxes/{address}/messages":{"get":{"operationId":"listMessages","tags":["mailboxes"],"summary":"List messages received by a mailbox","description":"Last 50 messages, newest first. Paid mailboxes include an `otp` field per message.","security":[{"mailboxSecret":[]}],"parameters":[{"name":"address","in":"path","required":true,"description":"The full address returned by POST /mailboxes, e.g. a1b2c3d4e5f6@receivemail.dev (URL-encode the @ if your client needs it).","schema":{"type":"string"}}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"type":"object","required":["address","messages"],"properties":{"address":{"type":"string"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"upgrade":{"type":"string","description":"Free tier only: present when a message contains a verification code."}}}}}},"401":{"description":"Missing or wrong mailbox secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mailboxes/{address}/wait":{"get":{"operationId":"waitForMessage","tags":["mailboxes"],"summary":"Long-poll for the next message","description":"Holds the request until a message newer than `since` arrives, then returns it; after `timeout` seconds returns `timed_out: true`. Call again on timeout.","security":[{"mailboxSecret":[]}],"parameters":[{"name":"address","in":"path","required":true,"description":"The full address returned by POST /mailboxes, e.g. a1b2c3d4e5f6@receivemail.dev (URL-encode the @ if your client needs it).","schema":{"type":"string"}},{"name":"timeout","in":"query","required":false,"description":"Seconds to wait, 1–25.","schema":{"type":"integer","minimum":1,"maximum":25,"default":25}},{"name":"since","in":"query","required":false,"description":"ISO 8601 timestamp; only messages received after it count.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"A message, or a timeout","content":{"application/json":{"schema":{"type":"object","required":["address","timed_out"],"properties":{"address":{"type":"string"},"timed_out":{"type":"boolean"},"message":{"oneOf":[{"$ref":"#/components/schemas/Message"},{"type":"null"}]},"upgrade":{"type":"string"}}}}}},"400":{"description":"since is not an ISO 8601 timestamp","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong mailbox secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"mailboxSecret":{"type":"http","scheme":"bearer","description":"The mailbox's own `secret` from POST /mailboxes."},"apiKey":{"type":"http","scheme":"bearer","description":"Paid API key (rmk_…), shown right after checkout at https://receivemail.dev/pricing."}},"schemas":{"Mailbox":{"type":"object","required":["address","expiresAt","secret"],"properties":{"address":{"type":"string","example":"a1b2c3d4e5f6@receivemail.dev"},"expiresAt":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"Bearer token for reading this mailbox. Only returned here."},"tier":{"type":"string","enum":["pro","webhooks"],"description":"Paid keys only."},"webhookUrl":{"type":["string","null"],"description":"Paid keys only."},"tip":{"type":"string","description":"Free tier only: informational."},"upgrade":{"type":"string","description":"Free tier only: informational."}}},"Message":{"type":"object","required":["from_address","received_at"],"properties":{"from_address":{"type":"string"},"subject":{"type":["string","null"]},"body_text":{"type":["string","null"],"description":"Plain-text body. No HTML or attachments."},"received_at":{"type":"string","format":"date-time"},"otp":{"type":["string","null"],"description":"Paid mailboxes only: the verification code found in the email."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"upgrade":{"type":"string"}}}}}}