{"openapi":"3.1.0","info":{"title":"BlinkInbox API","version":"1.0.0","description":"Programmable disposable inboxes for end-to-end tests, QA and AI agents. Create an inbox, trigger your signup flow, then wait for the email and read the OTP code or magic link.","contact":{"name":"BlinkInbox","url":"https://blinkinbox.club/contact"}},"servers":[{"url":"https://api.blinkinbox.club/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Inboxes"},{"name":"Messages"},{"name":"Domains"},{"name":"Webhooks"},{"name":"Account"}],"paths":{"/inboxes":{"post":{"tags":["Inboxes"],"operationId":"createInbox","summary":"Create an inbox","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prefix":{"type":"string","example":"signup","description":"Address starts with this, followed by 8 random characters."},"localPart":{"type":"string","example":"qa-bot","description":"Exact local part. Custom domains, or Pro on the shared domain."},"domain":{"type":"string","example":"test.acme.dev","description":"A verified custom domain. Defaults to the shared domain."},"ttlMinutes":{"type":"integer","example":60,"description":"Lifetime; max depends on plan."},"label":{"type":"string","example":"checkout-e2e #4821"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inbox"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"tags":["Inboxes"],"operationId":"listInboxes","summary":"List your inboxes","parameters":[{"name":"active","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}},{"name":"page","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Inbox"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/inboxes/{inbox}":{"parameters":[{"name":"inbox","in":"path","required":true,"description":"Inbox id or full address (e.g. `signup4k2j9x1a@blinkinbox.club`).","schema":{"type":"string"}}],"get":{"tags":["Inboxes"],"operationId":"getInbox","summary":"Get an inbox","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inbox"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Inboxes"],"operationId":"deleteInbox","summary":"Delete an inbox and all its mail","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/inboxes/{inbox}/messages":{"parameters":[{"name":"inbox","in":"path","required":true,"description":"Inbox id or full address (e.g. `signup4k2j9x1a@blinkinbox.club`).","schema":{"type":"string"}}],"get":{"tags":["Messages"],"operationId":"listMessages","summary":"List messages (newest first)","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only messages stored after this time."},{"name":"from","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the sender."},{"name":"subject","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the subject."},{"name":"unread","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}},{"name":"page","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MessageSummary"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/inboxes/{inbox}/messages/wait":{"parameters":[{"name":"inbox","in":"path","required":true,"description":"Inbox id or full address (e.g. `signup4k2j9x1a@blinkinbox.club`).","schema":{"type":"string"}}],"get":{"tags":["Messages"],"operationId":"waitForMessage","summary":"Long-poll until a matching message arrives","description":"Returns immediately if a matching message already exists. Without `since`, any message in the inbox matches, so you can call this after triggering the email without racing it.","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only messages stored after this time."},{"name":"from","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the sender."},{"name":"subject","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the subject."},{"name":"timeout","in":"query","schema":{"type":"integer","default":30,"maximum":60},"description":"Seconds to wait."},{"name":"otp","in":"query","schema":{"type":"boolean"},"description":"Only match messages with a code or verification link."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"408":{"$ref":"#/components/responses/Timeout"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/inboxes/{inbox}/otp":{"parameters":[{"name":"inbox","in":"path","required":true,"description":"Inbox id or full address (e.g. `signup4k2j9x1a@blinkinbox.club`).","schema":{"type":"string"}}],"get":{"tags":["Messages"],"operationId":"getLatestOtp","summary":"Latest OTP code / verification link","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only messages stored after this time."},{"name":"from","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the sender."},{"name":"subject","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the subject."},{"name":"timeout","in":"query","schema":{"type":"integer","default":0,"maximum":60},"description":"Seconds to wait for one to arrive."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Otp"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/inboxes/{inbox}/messages/{id}":{"parameters":[{"name":"inbox","in":"path","required":true,"description":"Inbox id or full address (e.g. `signup4k2j9x1a@blinkinbox.club`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Messages"],"operationId":"getMessage","summary":"Get a full message","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Messages"],"operationId":"deleteMessage","summary":"Delete a message","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/inboxes/{inbox}/messages/{id}/attachments/{attachmentId}":{"parameters":[{"name":"inbox","in":"path","required":true,"description":"Inbox id or full address (e.g. `signup4k2j9x1a@blinkinbox.club`).","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"attachmentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Messages"],"operationId":"downloadAttachment","summary":"Download an attachment","description":"Always served as application/octet-stream with Content-Disposition: attachment. Files that were not stored cannot be downloaded.","responses":{"200":{"description":"Binary","content":{"application/octet-stream":{}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"attachment_blocked: the file type is blocked for safety","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"attachment_too_large: the file exceeded the size limit and was not stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/domains":{"get":{"tags":["Domains"],"operationId":"listDomains","summary":"List custom domains","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Domains"],"operationId":"addDomain","summary":"Add a custom domain (Pro)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"test.acme.dev"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/domains/{id}/verify":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Domains"],"operationId":"verifyDomain","summary":"Re-check DNS records","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/domains/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"tags":["Domains"],"operationId":"deleteDomain","summary":"Remove a domain","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"operationId":"listWebhooks","summary":"List webhooks","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Webhooks"],"operationId":"createWebhook","summary":"Create a webhook","description":"Deliveries are signed: `BlinkInbox-Signature: t=<unix>,v1=<hex>` where v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). The secret is only returned on creation.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["email.received","inbox.expired"]}},"inbox":{"type":"string","description":"Limit to one inbox (id or address)."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"tags":["Webhooks"],"operationId":"deleteWebhook","summary":"Delete a webhook","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks/{id}/test":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Webhooks"],"operationId":"testWebhook","summary":"Send a test event","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"delivered":{"type":"boolean"},"lastStatus":{"type":["integer","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/me":{"get":{"tags":["Account"],"operationId":"getAccount","summary":"Plan, limits and usage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from the dashboard, e.g. `bb_live_...`. `X-API-Key` header also works."}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit or quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Timeout":{"description":"No matching message before the timeout (code `wait_timeout`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Success":{"type":"object","properties":{"success":{"type":"boolean"}}},"Inbox":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string","example":"signup4k2j9x1a@blinkinbox.club"},"localPart":{"type":"string"},"domain":{"type":"string"},"label":{"type":"string"},"source":{"type":"string","enum":["web","api","mcp"]},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},"MessageSummary":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"string"},"fromName":{"type":"string"},"subject":{"type":"string"},"preview":{"type":"string"},"receivedAt":{"type":"string","format":"date-time"},"read":{"type":"boolean"},"otp":{"type":["string","null"],"example":"482913","description":"Best-guess one-time code, extracted on arrival."},"verificationLink":{"type":["string","null"],"description":"Best-guess verify / magic-link URL."},"attachments":{"type":"integer"}}},"Message":{"allOf":[{"$ref":"#/components/schemas/MessageSummary"},{"type":"object","properties":{"to":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"codes":{"type":"array","items":{"type":"string"},"description":"All code candidates, best first."},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"text":{"type":"string"},"kind":{"type":"string","enum":["verification","other"]}}}},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"size":{"type":"integer"},"stored":{"type":"boolean","description":"False when the file was not kept; see `skipped`."},"skipped":{"type":["string","null"],"enum":["blocked_type","too_large","attachments_disabled",null],"description":"blocked_type: executables, scripts, installers, disk images, macro-enabled Office files, HTML and SVG are never stored. too_large: over the per-file or per-message size limit."},"archive":{"type":"boolean","description":"True for zip, rar, 7z and similar. Archive contents are not scanned."}}}}}}]},"Otp":{"type":"object","properties":{"otp":{"type":["string","null"]},"verificationLink":{"type":["string","null"]},"messageId":{"type":"string"},"from":{"type":"string"},"subject":{"type":"string"},"receivedAt":{"type":"string","format":"date-time"}}},"Domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["pending","verified"]},"txtVerified":{"type":"boolean"},"mxVerified":{"type":"boolean"},"dns":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"host":{"type":"string"},"value":{"type":"string"},"priority":{"type":"integer"}}}}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"inbox":{"type":["string","null"]},"active":{"type":"boolean"},"lastStatus":{"type":["integer","null"]},"failureCount":{"type":"integer"},"secret":{"type":"string","description":"Only on create."}}}}}}