{"openapi":"3.1.2","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"TempMailGrab API","version":"1.0.0","description":"Create disposable email inboxes and read mail programmatically. OTP codes and verification links are auto-extracted from every message. Install the [official JavaScript and TypeScript SDK](https://www.npmjs.com/package/tempmailgrab) for typed clients and test-runner helpers.","contact":{"email":"api@tempmailgrab.com"},"license":{"name":"Proprietary","url":"https://tempmailgrab.com/terms"}},"externalDocs":{"description":"Developer API guide, examples, webhooks, and SDK documentation","url":"https://tempmailgrab.com/api-docs"},"servers":[{"url":"https://tempmailgrab.com/api/v1"}],"security":[{"bearerAuth":[]},{"apiKey":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Inbox":{"type":"object","required":["id","address","created_at","expires_at"],"properties":{"id":{"type":"string"},"address":{"type":"string","format":"email"},"created_at":{"type":"integer","description":"Unix timestamp in seconds."},"expires_at":{"type":"integer","description":"Unix timestamp in seconds."}}},"MessageSummary":{"type":"object","required":["id","sender","subject","snippet","extracted_otp","created_at"],"properties":{"id":{"type":"string"},"sender":{"type":"string"},"subject":{"type":["string","null"]},"snippet":{"type":"string"},"extracted_otp":{"type":["string","null"]},"created_at":{"type":"integer","description":"Unix timestamp in seconds."}}},"MessageDetail":{"type":"object","required":["id","sender","subject","text_body","html_body","extracted_otp","extracted_links","raw_headers","timestamp","attachments"],"properties":{"id":{"type":"string"},"sender":{"type":"string"},"subject":{"type":["string","null"]},"text_body":{"type":["string","null"]},"html_body":{"type":["string","null"],"description":"Sanitized HTML."},"extracted_otp":{"type":["string","null"]},"extracted_links":{"type":"array","items":{"type":"string","format":"uri"}},"raw_headers":{"type":["string","null"]},"timestamp":{"type":"integer","description":"Unix timestamp in seconds."},"attachments":{"type":"array","items":{"type":"object","required":["id","filename","content_type","size","url"],"properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"content_type":{"type":["string","null"]},"size":{"type":"integer","minimum":0},"url":{"type":"string","format":"uri"}}}}}},"WebhookMessage":{"type":"object","required":["id","inbox_address","sender","subject","text_body","html_body","extracted_otp","extracted_links","timestamp"],"properties":{"id":{"type":"string"},"inbox_address":{"type":"string","format":"email"},"sender":{"type":"string"},"subject":{"type":["string","null"]},"text_body":{"type":["string","null"]},"html_body":{"type":["string","null"]},"extracted_otp":{"type":["string","null"]},"extracted_links":{"type":"array","items":{"type":"string","format":"uri"}},"timestamp":{"type":"integer","description":"Unix timestamp in seconds."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"AuthenticationError":{"description":"Missing or invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/inbox":{"post":{"operationId":"createInbox","summary":"Create a disposable inbox","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prefix":{"type":"string"},"domain":{"type":"string"},"ttl_seconds":{"type":"integer","minimum":600,"default":86400,"maximum":259200}}}}}},"responses":{"201":{"description":"Created inbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inbox"}}}},"400":{"description":"Invalid prefix, domain, or TTL"},"429":{"description":"Rate limited"}}}},"/inbox/{id}":{"delete":{"operationId":"deleteInbox","summary":"Delete an inbox and all of its mail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"404":{"description":"Not found or expired"}}}},"/inbox/{id}/messages":{"get":{"operationId":"listInboxMessages","summary":"List messages (newest first)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Message list","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/MessageSummary"}}}}}}},"401":{"$ref":"#/components/responses/AuthenticationError"}}},"delete":{"operationId":"deleteInboxMessages","summary":"Delete every message in an inbox, keeping the address","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted count"},"401":{"$ref":"#/components/responses/AuthenticationError"}}}},"/inbox/{id}/messages/{mid}":{"get":{"operationId":"getInboxMessage","summary":"Fetch one full message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"mid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Full message with HTML body, OTP, links, and attachments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetail"}}}},"404":{"description":"Message not found"}}}},"/inbox/{id}/test-message":{"post":{"operationId":"createTestMessage","summary":"Inject a synthetic message through the parsing and realtime pipeline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sender":{"type":"string"},"subject":{"type":"string"},"text":{"type":"string"}}}}}},"responses":{"200":{"description":"Synthetic message created"},"404":{"description":"Inbox not found or expired"}}}},"/messages":{"get":{"operationId":"listMessages","summary":"List messages using the flat endpoint alias","parameters":[{"name":"inbox","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Message list"},"404":{"description":"Inbox not found or expired"}}}},"/messages/{id}":{"get":{"operationId":"getMessage","summary":"Fetch one message by ID (flat alias)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Full message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetail"}}}},"404":{"description":"Message not found"}}}},"/inbox/{id}/webhook":{"post":{"operationId":"createInboxWebhook","summary":"Register a delivery webhook for one inbox","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Webhook registered with its signing secret"},"401":{"$ref":"#/components/responses/AuthenticationError"}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List account webhooks","responses":{"200":{"description":"Webhook list"},"401":{"$ref":"#/components/responses/AuthenticationError"}}},"post":{"operationId":"createWebhook","summary":"Register an account webhook (fires for every inbox)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"201":{"description":"Webhook registered with HMAC secret"},"401":{"$ref":"#/components/responses/AuthenticationError"}}}},"/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Delete an account webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deletion result"},"401":{"$ref":"#/components/responses/AuthenticationError"}}}},"/byod":{"get":{"operationId":"listCustomDomains","summary":"List custom domains registered to this API key","responses":{"200":{"description":"Custom-domain list"},"401":{"$ref":"#/components/responses/AuthenticationError"}}},"post":{"operationId":"createCustomDomain","summary":"Register a custom domain and receive its DNS requirements","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"mail.example.com"}}}}}},"responses":{"201":{"description":"Pending custom domain and required MX/TXT records"},"409":{"description":"Domain already registered"}}}},"/byod/{domain}/verify":{"post":{"operationId":"verifyCustomDomain","summary":"Verify custom-domain TXT ownership and MX routing","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"DNS verification result"},"404":{"description":"Domain not registered to this key"}}}}},"webhooks":{"messageReceived":{"post":{"operationId":"messageReceivedWebhook","summary":"A parsed message was received","description":"Signed with HMAC-SHA256 in X-TMG-Signature using the secret returned when the webhook was created.","parameters":[{"name":"X-TMG-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","sent_at","data"],"properties":{"event":{"type":"string","const":"email.received"},"sent_at":{"type":"integer","description":"Unix timestamp in seconds."},"data":{"$ref":"#/components/schemas/WebhookMessage"}}}}}},"responses":{"200":{"description":"Return any 2xx response to acknowledge delivery."}}}}}}