{"openapi":"3.1.0","info":{"title":"TempBooth API","version":"1.0.0","description":"Receive-only disposable email inboxes for tests and automation. Create an inbox, poll for messages, and read the extracted verification code. Access is by API key (request one at https://temp-mailx.com/api).","contact":{"name":"TempBooth","url":"https://temp-mailx.com/api"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://temp-mailx.com/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"inboxes","description":"Create and read disposable inboxes"},{"name":"messages","description":"Read received messages"},{"name":"domains","description":"Domains the API issues addresses on"}],"paths":{"/inboxes":{"post":{"tags":["inboxes"],"summary":"Create a disposable inbox","description":"Creates an inbox in the API domain pool and returns it together with a one-time, inbox-scoped read token. Requires a master API key (not an inbox token).","operationId":"createInbox","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"domainId":{"type":"string","description":"Optionally pin a specific API domain (see GET /domains)."}}}}}},"responses":{"201":{"description":"Inbox created","content":{"application/json":{"schema":{"type":"object","required":["inbox","token"],"properties":{"inbox":{"$ref":"#/components/schemas/Inbox"},"token":{"type":"string","description":"One-time inbox-scoped read token (tbi_…). Shown once."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/inboxes/{id}":{"get":{"tags":["inboxes"],"summary":"Get an inbox","operationId":"getInbox","parameters":[{"$ref":"#/components/parameters/InboxId"}],"responses":{"200":{"description":"The inbox","content":{"application/json":{"schema":{"type":"object","properties":{"inbox":{"$ref":"#/components/schemas/Inbox"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/inboxes/{id}/messages":{"get":{"tags":["messages"],"summary":"List messages in an inbox (newest first)","operationId":"listMessages","parameters":[{"$ref":"#/components/parameters/InboxId"}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"type":"object","properties":{"inbox":{"$ref":"#/components/schemas/Inbox"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/MessageSummary"}},"delivery":{"type":"object","properties":{"delayed":{"type":"boolean"},"lagSeconds":{"type":"number"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/inboxes/{id}/messages/{messageId}":{"get":{"tags":["messages"],"summary":"Read one full message","description":"Marks the message read and returns the full body plus the extracted verification code.","operationId":"getMessage","parameters":[{"$ref":"#/components/parameters/InboxId"},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The message","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/Message"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/inboxes/{id}/events":{"get":{"tags":["messages"],"summary":"Server-Sent Events stream of new-message notifications","description":"Opens a text/event-stream. Emits `message-received`, `inbox-expired` and `inbox-deleted` events. Authenticate with the bearer header (a browser EventSource cannot set it; use a fetch/library SSE client).","operationId":"streamEvents","parameters":[{"$ref":"#/components/parameters/InboxId"}],"responses":{"200":{"description":"An event stream (text/event-stream)."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/domains":{"get":{"tags":["domains"],"summary":"List the domains the API issues addresses on","description":"Public — no authentication required.","operationId":"listDomains","security":[],"responses":{"200":{"description":"Domain names","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"string"}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A master API key (tbk_live_…) or an inbox-scoped read token (tbi_…)."}},"parameters":{"InboxId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Inbox id."}},"responses":{"Unauthorized":{"description":"Missing or invalid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The credential is not allowed to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such resource for this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit or quota exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"The API is paused or no API-pool domain is available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Inbox":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string","format":"email"},"domain":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"contentDeletedAt":{"type":"string","format":"date-time"},"secondsUntilExpiry":{"type":"integer"},"receiving":{"type":"boolean"},"messageCount":{"type":"integer"},"unreadCount":{"type":"integer"}}},"MessageSummary":{"type":"object","properties":{"id":{"type":"string"},"from":{"$ref":"#/components/schemas/Address"},"subject":{"type":["string","null"]},"preview":{"type":"string"},"receivedAt":{"type":"string","format":"date-time"},"read":{"type":"boolean"},"hasAttachments":{"type":"boolean"}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"from":{"$ref":"#/components/schemas/Address"},"to":{"type":"string","format":"email"},"subject":{"type":["string","null"]},"receivedAt":{"type":"string","format":"date-time"},"sentAt":{"type":["string","null"],"format":"date-time"},"text":{"type":["string","null"]},"html":{"type":["string","null"]},"verificationCode":{"type":["string","null"],"description":"OTP/verification code extracted from the body, if found."},"hasAttachments":{"type":"boolean"},"remoteImageCount":{"type":"integer"},"read":{"type":"boolean"}}},"Address":{"type":"object","properties":{"name":{"type":["string","null"]},"address":{"type":["string","null"]}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable error code."},"message":{"type":"string"}}}}}}