{ "openapi": "3.0.3", "info": { "title": "Best Temp Mail API", "version": "1", "description": "Create disposable email inboxes and read what arrives, for automated\ntesting, CI pipelines, and signup verification flows.\n\n### Delivery methods\n\nFour ways to receive mail, in rough order of how most callers use them:\n\n- **Polling** `GET /inboxes/{address}/messages`\n- **Long poll** `GET /inboxes/{address}/wait` holds the connection open up to 55s and returns the moment mail arrives\n- **WebSocket** `wss://api.best-tempmail.com/ws` for a persistent connection\n- **Webhooks** we POST to your own URL, signed so you can verify it came from us\n\n### Plans\n\n| Capability | Free | Founders / Developer | Pro |\n| --- | :-: | :-: | :-: |\n| Requests per hour | 150 | 2000 | 5000 |\n| Burst per 10s | 100 | 300 | 300 |\n| Inbox creation | 3/day per IP | unlimited | unlimited |\n| Inbox lifetime | 2 hours | 2 hours | 24 hours |\n| Polling, wait, WebSocket | yes | yes | yes |\n| Webhooks | no | yes | yes |\n| OTP extraction | no | yes | yes |\n| Attachment downloads | no | no | yes |\n| Concurrent waits | 5 | 5 | 20 |\n| Commercial use | no | yes | yes |\n\nFree access needs no key at all. Paid keys are sent in the `x-api-key` header.", "contact": { "name": "Support", "email": "support@best-tempmail.com", "url": "https://best-tempmail.com/api" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.best-tempmail.com/v1", "description": "Production" } ], "tags": [ { "name": "Inboxes", "description": "Create, inspect and delete inboxes" }, { "name": "Messages", "description": "Read mail and extract codes" }, { "name": "Attachments", "description": "Download files from a message (Pro)" }, { "name": "Webhooks", "description": "Receive mail on your own server (paid)" }, { "name": "Service", "description": "Domains, health and stats" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Paid plan key, issued after purchase. Omit it entirely to use the free tier, which is keyless and rate limited per IP." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable explanation." }, "request_id": { "type": "string", "description": "Quote this when contacting support about a request." }, "plan": { "type": "string", "description": "Caller's current plan, on 402 responses." }, "upgrade": { "type": "string", "format": "uri" } }, "required": [ "error" ] }, "Inbox": { "type": "object", "properties": { "success": { "type": "boolean" }, "address": { "type": "string", "format": "email" }, "created_at": { "type": "string" }, "expires_at": { "type": "string", "description": "2 hours after creation on Free and Developer, 24 hours on Pro." } } }, "MessageSummary": { "type": "object", "properties": { "id": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" }, "date": { "type": "string", "format": "date-time", "nullable": true }, "has_attachments": { "type": "boolean" } } }, "Attachment": { "type": "object", "properties": { "index": { "type": "integer", "description": "Position in this message. Use this, not the id, to download: ids are regenerated on every read and do not survive a round trip." }, "filename": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer", "description": "Bytes." }, "downloadable": { "type": "boolean", "description": "Whether THIS caller can download it. False on plans below Pro, and false for anything above 4 MB." }, "download_url": { "type": "string", "description": "Present only when downloadable is true." }, "requires_plan": { "type": "string", "description": "Present when the caller's plan is too low." } } }, "MessageFull": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "properties": { "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "subject": { "type": "string" }, "date": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } } } } }, "OtpResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "message_id": { "type": "string" }, "code": { "type": "string", "nullable": true, "description": "Null when no candidate scored highly enough to be trusted." }, "confidence": { "type": "string", "enum": [ "high", "medium", "low", "none" ], "description": "How clearly the winner beat the other candidates. Treat 'low' as worth checking against the candidates list." }, "candidates": { "type": "array", "description": "Runners-up, so a wrong pick can be spotted and reported.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "score": { "type": "integer" } } } } } }, "WebhookPayload": { "type": "object", "description": "POSTed to your registered URL when mail arrives. Verify the X-BTM-Signature header before trusting it.", "properties": { "event": { "type": "string", "enum": [ "message.received" ] }, "timestamp": { "type": "integer", "description": "Unix seconds." }, "address": { "type": "string", "format": "email" }, "message": { "$ref": "#/components/schemas/MessageSummary" } } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests permitted this hour on the caller's plan.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds at which the hourly window resets.", "schema": { "type": "integer" } }, "X-Request-ID": { "description": "Identifier for this request, useful in support queries.", "schema": { "type": "string" } } } }, "security": [ { "ApiKeyAuth": [] }, {} ], "paths": { "/domains": { "get": { "tags": [ "Service" ], "summary": "List the domains inboxes can be created on", "description": "Fetch this rather than hardcoding a domain: the list changes as domains are added or rotated, and callers who read it keep working.", "security": [ {} ], "responses": { "200": { "description": "Current domains.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" } } } }, "example": { "domains": [ "dextde.site", "linsal.site", "martaz.site", "simtim.site", "alagen.site" ] } } } } } } }, "/health": { "get": { "tags": [ "Service" ], "summary": "Service health", "security": [ {} ], "responses": { "200": { "description": "Service is up.", "content": { "application/json": { "example": { "status": "ok", "version": "1", "time": "2026-09-07T12:00:00.000Z" } } } } } } }, "/stats": { "get": { "tags": [ "Service" ], "summary": "Caller's current usage and limits", "responses": { "200": { "description": "Usage for the current hour." } } } }, "/inboxes": { "post": { "tags": [ "Inboxes" ], "summary": "Create an inbox", "description": "Creates a disposable inbox. Both fields are optional: omit them and\na random local part on a random domain is chosen.\n\nFree callers may create 3 inboxes per day per IP.\nPaid callers are unlimited.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Local part, lowercase letters, digits, dot, underscore and hyphen only. Max 64 characters." }, "domain": { "type": "string", "description": "One of the domains from GET /domains." } } }, "example": { "username": "signup-test", "domain": "dextde.site" } } } }, "responses": { "200": { "description": "Inbox created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "400": { "description": "Invalid username or unknown domain." }, "409": { "description": "That address already exists and is active." }, "429": { "description": "Hourly quota or burst limit exceeded. Retry after the window resets; see the X-RateLimit-Reset header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxes/{address}": { "get": { "tags": [ "Inboxes" ], "summary": "Inbox metadata", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The full inbox address, for example abc1234@dextde.site.", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "Creation and expiry times." }, "404": { "description": "The inbox or message does not exist, or has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Inboxes" ], "summary": "Delete an inbox and its messages", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The full inbox address, for example abc1234@dextde.site.", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "Deleted." }, "404": { "description": "The inbox or message does not exist, or has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxes/{address}/messages": { "get": { "tags": [ "Messages" ], "summary": "List messages", "description": "Newest first. Returns summaries; fetch a single message for its body.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The full inbox address, for example abc1234@dextde.site.", "schema": { "type": "string", "format": "email" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 100 }, "description": "Maximum messages to return." } ], "responses": { "200": { "description": "Messages in this inbox.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "address": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageSummary" } } } } } } }, "404": { "description": "The inbox or message does not exist, or has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Hourly quota or burst limit exceeded. Retry after the window resets; see the X-RateLimit-Reset header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxes/{address}/wait": { "get": { "tags": [ "Messages" ], "summary": "Wait for the next message (long poll)", "description": "Holds the connection open until mail arrives or the timeout expires,\nreplacing a polling loop with a single call.\n\nA timeout is **not** an error: it returns 200 with `message: null`,\nso a caller can loop again without treating it as a failure.\n\nWithout `since`, messages already present when the call starts are\ntreated as seen, so only genuinely new mail is returned.\n\nConcurrent waits are capped at 5 per caller, 20 on Pro.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The full inbox address, for example abc1234@dextde.site.", "schema": { "type": "string", "format": "email" } }, { "name": "timeout", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 55 }, "description": "Seconds to wait. Clamped to 55." }, { "name": "since", "in": "query", "schema": { "type": "string" }, "description": "Return the first message that is not this id. Use it to resume from a known point without missing anything." } ], "responses": { "200": { "description": "Either a message, or a timeout with message null.", "content": { "application/json": { "examples": { "arrived": { "summary": "Mail arrived", "value": { "success": true, "address": "abc1234@dextde.site", "message": { "id": "a1b2c3d4e5f6a7b8", "from": "\"Service\" ", "subject": "Your verification code", "date": "2026-09-07T12:00:00.000Z", "has_attachments": false } } }, "timedOut": { "summary": "Nothing arrived in time", "value": { "success": true, "address": "abc1234@dextde.site", "message": null, "timed_out": true, "waited_seconds": 30 } } } } } }, "404": { "description": "The inbox or message does not exist, or has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many concurrent waits from this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxes/{address}/messages/{id}": { "get": { "tags": [ "Messages" ], "summary": "Read one message", "description": "Scoped to the inbox: a message id from another address returns 404, even though both share a domain.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The full inbox address, for example abc1234@dextde.site.", "schema": { "type": "string", "format": "email" } }, { "name": "id", "in": "path", "required": true, "description": "Message id as returned by the message list.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full message with body and attachment metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageFull" } } } }, "404": { "description": "The inbox or message does not exist, or has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxes/{address}/messages/{id}/otp": { "get": { "tags": [ "Messages" ], "summary": "Extract the verification code (paid)", "description": "Returns the verification code from a message, so you do not have to\nwrite a parser for every sender's format.\n\nCandidates are scored on the words around them, their length and\nposition, and the best is returned with the runners-up. When nothing\nscores highly enough, `code` is null rather than a guess: a wrong code\nbreaks a test in a way that is hard to debug.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The full inbox address, for example abc1234@dextde.site.", "schema": { "type": "string", "format": "email" } }, { "name": "id", "in": "path", "required": true, "description": "Message id as returned by the message list.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Best candidate, with alternatives.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpResult" }, "example": { "success": true, "message_id": "a1b2c3d4e5f6a7b8", "code": "889231", "confidence": "high", "candidates": [ { "code": "889231", "score": 8 }, { "code": "293679", "score": 2 } ] } } } }, "402": { "description": "The caller's plan does not include this capability. The body names the required plan and links to pricing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "OTP extraction requires a paid plan.", "plan": "Free", "upgrade": "https://best-tempmail.com/api/pricing", "request_id": "a1b2c3d4e5f6a7b8" } } } }, "404": { "description": "The inbox or message does not exist, or has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxes/{address}/messages/{id}/attachments/{index}": { "get": { "tags": [ "Attachments" ], "summary": "Download an attachment (Pro)", "description": "Returns the raw file with Content-Type and Content-Disposition set,\nso `curl -O` and browsers save it correctly.\n\nAttachments above 4 MB are refused with 413. In practice\nnothing legitimate reaches that: the mail server accepts messages up\nto 5 MB, and base64 inflates binary data by about a third.\n\nLower plans still see attachment metadata on the message itself.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The full inbox address, for example abc1234@dextde.site.", "schema": { "type": "string", "format": "email" } }, { "name": "id", "in": "path", "required": true, "description": "Message id as returned by the message list.", "schema": { "type": "string" } }, { "name": "index", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 }, "description": "Index from the message's attachments array." } ], "responses": { "200": { "description": "The file.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "402": { "description": "The caller's plan does not include this capability. The body names the required plan and links to pricing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "OTP extraction requires a paid plan.", "plan": "Free", "upgrade": "https://best-tempmail.com/api/pricing", "request_id": "a1b2c3d4e5f6a7b8" } } } }, "404": { "description": "The inbox or message does not exist, or has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Attachment exceeds the size that can be served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Register a webhook URL (paid)", "description": "Registers where mail should be POSTed. One URL per key; registering\nagain replaces it and issues a new signing secret, which is how you\nrotate that secret.\n\nThe URL must be https and must resolve to a public host. Private and\nloopback addresses are refused, because otherwise this endpoint could\nbe used to make this server call its own internals.\n\n**Verifying a delivery:** compute\n`base64(HMAC_SHA256(secret, X-BTM-Timestamp + '.' + rawBody))` and\ncompare it with the `X-BTM-Signature` header, which is sent as `v1,`.\n\nFailed deliveries are retried three times with growing gaps. After\nrepeated failures across many messages the webhook is disabled, and\nregistering again re-enables it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } }, "example": { "url": "https://your-server.com/hooks/mail" } } } }, "responses": { "200": { "description": "Registered. The secret is shown once, here.", "content": { "application/json": { "example": { "success": true, "url": "https://your-server.com/hooks/mail", "secret": "whsec_...", "note": "Store this secret. It is shown once." } } } }, "400": { "description": "Missing, malformed, non-https, or private-host URL." }, "402": { "description": "The caller's plan does not include this capability. The body names the required plan and links to pricing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "OTP extraction requires a paid plan.", "plan": "Free", "upgrade": "https://best-tempmail.com/api/pricing", "request_id": "a1b2c3d4e5f6a7b8" } } } } } }, "get": { "tags": [ "Webhooks" ], "summary": "Current webhook and recent deliveries (paid)", "description": "Includes the last delivery attempts with status codes and errors, so you can debug your own endpoint without contacting support.", "responses": { "200": { "description": "Registration plus recent attempts." }, "402": { "description": "The caller's plan does not include this capability. The body names the required plan and links to pricing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "OTP extraction requires a paid plan.", "plan": "Free", "upgrade": "https://best-tempmail.com/api/pricing", "request_id": "a1b2c3d4e5f6a7b8" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Stop sending webhooks (paid)", "responses": { "200": { "description": "Removed." }, "402": { "description": "The caller's plan does not include this capability. The body names the required plan and links to pricing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "OTP extraction requires a paid plan.", "plan": "Free", "upgrade": "https://best-tempmail.com/api/pricing", "request_id": "a1b2c3d4e5f6a7b8" } } } } } } } } }