{"openapi":"3.0.0","info":{"title":"throwaway.cloud API","version":"3.0.0","description":"API for detecting disposable/throwaway email domains with trait-based analysis","contact":{"name":"Iocium","email":"throwaway-support@iocium.com"},"license":{"name":"Apache-2.0","url":"http://www.apache.org/licenses/LICENSE-2.0"}},"servers":[{"url":"https://throwaway.cloud","description":"Production"},{"url":"https://staging.throwaway.cloud","description":"Staging"}],"paths":{"/api/v3/{subject}":{"get":{"summary":"Check email or domain traits (v3)","description":"Advanced endpoint with trait-based analysis including DNS validation, caching, and rate limiting. Returns an array of traits instead of a boolean flag.","parameters":[{"name":"subject","in":"path","required":true,"description":"Email address or domain name to analyze","schema":{"type":"string","example":"test@example.com"}}],"responses":{"200":{"description":"Trait analysis result","headers":{"X-RateLimit-Limit":{"description":"Rate limit maximum requests","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Rate limit remaining requests","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Rate limit reset time (unix timestamp)","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"traits":{"type":"array","items":{"type":"string","enum":["disposable","allowlist","false_positive","no_mx","no_mx_ip","suspicious_mx","suspicious_ns","suspicious_ip","suspicious_pattern","suspicious_tld","rbl_listed"]},"description":"Array of traits identified for the domain","examples":[["allowlist"],["disposable"],["disposable","no_mx_ip"],["no_mx"],["no_mx_ip"],["suspicious_mx"],["suspicious_ns"],["suspicious_ip"],["suspicious_pattern"],["suspicious_tld"],["rbl_listed"],[]]},"records":{"type":"object","description":"DNS records for the domain (when available)","properties":{"nameservers":{"type":"array","description":"NS records for the domain","items":{"type":"object","properties":{"nameserver":{"type":"string","description":"Nameserver hostname","example":"ns1.example.com"}},"required":["nameserver"]}},"mx_records":{"type":"array","description":"MX records for the domain","items":{"type":"object","properties":{"priority":{"type":"integer","description":"MX priority value","example":10},"exchange":{"type":"string","description":"Mail exchange hostname","example":"mail.example.com"}},"required":["priority","exchange"]}},"mx_ips":{"type":"array","description":"IP addresses for MX records","items":{"type":"object","properties":{"exchange":{"type":"string","description":"Mail exchange hostname","example":"mail.example.com"},"ips":{"type":"array","description":"IP addresses (IPv4 and IPv6) for the MX server","items":{"type":"string","description":"IP address","example":"192.168.1.100"},"example":["192.168.1.100","2001:db8::1"]}},"required":["exchange","ips"]}}}}},"required":["success","traits"]},"examples":{"legitimate-domain":{"summary":"Legitimate domain (allowlisted)","value":{"success":true,"traits":["allowlist"],"records":{"nameservers":[{"nameserver":"ns1.google.com"},{"nameserver":"ns2.google.com"}],"mx_records":[{"priority":10,"exchange":"smtp.gmail.com"},{"priority":20,"exchange":"alt1.gmail-smtp-in.l.google.com"}],"mx_ips":[{"exchange":"smtp.gmail.com","ips":["142.251.30.27","2a00:1450:400c:c09::1a"]},{"exchange":"alt1.gmail-smtp-in.l.google.com","ips":["172.253.113.26"]}]}}},"disposable":{"summary":"Disposable domain","value":{"success":true,"traits":["disposable"],"records":{"nameservers":[{"nameserver":"ns1.suspicious-provider.com"}],"mx_records":[{"priority":10,"exchange":"mail.tempmail-service.com"}],"mx_ips":[{"exchange":"mail.tempmail-service.com","ips":["192.168.1.100"]}]}}},"no-mx-domain":{"summary":"Domain with no MX record","value":{"success":true,"traits":["no_mx"],"records":{"nameservers":[{"nameserver":"ns1.example.com"}]}}},"disposable-no-mx-ip":{"summary":"Disposable domain with MX but no A/AAAA records","value":{"success":true,"traits":["disposable","no_mx_ip"],"records":{"nameservers":[{"nameserver":"ns1.suspicious-provider.com"}],"mx_records":[{"priority":10,"exchange":"nonexistent.mail.com"}],"mx_ips":[{"exchange":"nonexistent.mail.com","ips":[]}]}}},"clean-domain":{"summary":"Clean domain with no issues","value":{"success":true,"traits":[],"records":{"nameservers":[{"nameserver":"ns1.example.com"},{"nameserver":"ns2.example.com"}],"mx_records":[{"priority":10,"exchange":"mail.example.com"}],"mx_ips":[{"exchange":"mail.example.com","ips":["203.0.113.10","2001:db8::1"]}]}}},"minimal-response":{"summary":"Minimal response without DNS records","value":{"success":true,"traits":["suspicious_pattern"]}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retry","schema":{"type":"integer"}}}}}}},"/api/v2/{subject}":{"get":{"summary":"Check if email or domain is disposable (v2)","description":"Advanced endpoint with DNS checks, caching, and rate limiting","parameters":[{"name":"subject","in":"path","required":true,"description":"Email address or domain name to check","schema":{"type":"string","example":"test@example.com"}}],"responses":{"200":{"description":"Check result","headers":{"X-RateLimit-Limit":{"description":"Rate limit maximum requests","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Rate limit remaining requests","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Rate limit reset time (unix timestamp)","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"isDisposable":{"type":"boolean"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retry","schema":{"type":"integer"}}}}}}},"/api/v1/domain/{domain}":{"get":{"summary":"Check if domain is disposable (v1)","description":"Simple domain check against database.\n\n**Deprecated:** This v1 endpoint is scheduled for sunset on 1 December 2026. Please migrate to /api/v2 or /api/v3.","deprecated":true,"parameters":[{"name":"domain","in":"path","required":true,"description":"Domain name to check","schema":{"type":"string","example":"example.com"}}],"responses":{"200":{"description":"Check result","headers":{"Deprecation":{"description":"Indicates that this API version is deprecated.","schema":{"type":"string","example":"true"}},"Sunset":{"description":"Date and time after which this API version will no longer be available.","schema":{"type":"string","example":"Tue, 01 Dec 2026 00:00:00 GMT"}},"Link":{"description":"Link to the successor API version.","schema":{"type":"string","example":"</api/v3/>; rel=\"successor-version\""}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"isDisposable":{"type":"boolean"}}}}}}}}},"/api/v1/email/{email}":{"get":{"summary":"Check if email is disposable (v1)","description":"Simple email check against database.\n\n**Deprecated:** This v1 endpoint is scheduled for sunset on 1 December 2026. Please migrate to /api/v2 or /api/v3.","deprecated":true,"parameters":[{"name":"email","in":"path","required":true,"description":"Email address to check","schema":{"type":"string","example":"test@example.com"}}],"responses":{"200":{"description":"Check result","headers":{"Deprecation":{"description":"Indicates that this API version is deprecated.","schema":{"type":"string","example":"true"}},"Sunset":{"description":"Date and time after which this API version will no longer be available.","schema":{"type":"string","example":"Tue, 01 Dec 2026 00:00:00 GMT"}},"Link":{"description":"Link to the successor API version.","schema":{"type":"string","example":"</api/v3/>; rel=\"successor-version\""}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"isDisposable":{"type":"boolean"}}}}}}}}},"/list.json":{"get":{"summary":"Download domain list as JSON","description":"Get the complete list of disposable domains in JSON format","responses":{"200":{"description":"Domain list","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}}}}},"/list.txt":{"get":{"summary":"Download domain list as text","description":"Get the complete list of disposable domains as plain text","responses":{"200":{"description":"Domain list","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/list.yaml":{"get":{"summary":"Download domain list as YAML","description":"Get the complete list of disposable domains in YAML format","responses":{"200":{"description":"Domain list","content":{"application/yaml":{"schema":{"type":"string"}}}}}}},"/dns-query":{"get":{"summary":"DNS-over-HTTPS query (RFC 8484)","description":"Perform DNS queries using DNS-over-HTTPS wire format. Returns sinkhole IP addresses for disposable domains.","parameters":[{"name":"dns","in":"query","required":true,"description":"Base64url-encoded DNS query message","schema":{"type":"string","example":"AAABAAABAAAAAAAAB3Rlc3RtYWlsBGFyZXMAAQAB"}}],"responses":{"200":{"description":"DNS response in wire format","content":{"application/dns-message":{"schema":{"type":"string","format":"binary","description":"DNS response message in wire format"}}}},"400":{"description":"Invalid DNS query format"}}},"post":{"summary":"DNS-over-HTTPS query (RFC 8484)","description":"Perform DNS queries using DNS-over-HTTPS wire format. Returns sinkhole IP addresses for disposable domains.","requestBody":{"required":true,"content":{"application/dns-message":{"schema":{"type":"string","format":"binary","description":"DNS query message in wire format"}}}},"responses":{"200":{"description":"DNS response in wire format","content":{"application/dns-message":{"schema":{"type":"string","format":"binary","description":"DNS response message in wire format"}}}},"400":{"description":"Invalid DNS query format"}}}},"/resolve":{"get":{"summary":"DNS-over-JSON query (RFC 8427)","description":"Perform DNS queries using JSON format. Returns sinkhole IP addresses for disposable domains.","parameters":[{"name":"name","in":"query","required":true,"description":"Domain name to resolve","schema":{"type":"string","example":"testmail.ares"}},{"name":"type","in":"query","required":false,"description":"DNS record type (A, AAAA, MX, etc.)","schema":{"type":"string","default":"A","enum":["A","AAAA","MX","NS","TXT","CNAME","SOA"]}},{"name":"cd","in":"query","required":false,"description":"Checking Disabled flag","schema":{"type":"boolean","default":false}},{"name":"do","in":"query","required":false,"description":"DNSSEC OK flag","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"DNS response in JSON format","content":{"application/dns-json":{"schema":{"type":"object","properties":{"Status":{"type":"integer","description":"DNS response code (0=NOERROR, 3=NXDOMAIN, etc.)"},"TC":{"type":"boolean","description":"Truncated response"},"RD":{"type":"boolean","description":"Recursion Desired"},"RA":{"type":"boolean","description":"Recursion Available"},"AD":{"type":"boolean","description":"Authenticated Data"},"CD":{"type":"boolean","description":"Checking Disabled"},"Question":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"integer"}}}},"Answer":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"integer"},"TTL":{"type":"integer"},"data":{"type":"string"}}}}}}}}},"400":{"description":"Invalid query parameters"}}}}}}