{"openapi":"3.0.3","info":{"title":"Email DNS Deliverability Auditor API","version":"1.0.0","description":"Audits MX, SPF, DKIM selectors, DMARC, and MTA-STS records via DNS-over-HTTPS, returning a 0-100 deliverability score, grade, and exact DNS fix instructions."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"EmailDnsResponse":{"type":"object","properties":{"domain":{"type":"string","example":"tinplate.dev"},"score":{"type":"integer","minimum":0,"maximum":100,"example":85},"grade":{"type":"string","enum":["A","B","C","D","F"],"example":"B"},"checks":{"type":"object","properties":{"mx":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"],"example":"pass"},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0,"exclusiveMinimum":true},"records":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true}},"required":["status","score","max_score","records","issues","fix"]},"spf":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"],"example":"pass"},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0,"exclusiveMinimum":true},"records":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true}},"required":["status","score","max_score","records","issues","fix"]},"dmarc":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"],"example":"pass"},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0,"exclusiveMinimum":true},"records":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true}},"required":["status","score","max_score","records","issues","fix"]},"dkim":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"],"example":"pass"},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0,"exclusiveMinimum":true},"records":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true},"found_selectors":{"type":"array","items":{"type":"string"}},"checked_selectors":{"type":"array","items":{"type":"string"}}},"required":["status","score","max_score","records","issues","fix","found_selectors","checked_selectors"]},"mta_sts":{"type":"object","properties":{"status":{"type":"string","enum":["pass","warn","fail"],"example":"pass"},"score":{"type":"integer","minimum":0},"max_score":{"type":"integer","minimum":0,"exclusiveMinimum":true},"records":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"string"}},"fix":{"type":"string","nullable":true}},"required":["status","score","max_score","records","issues","fix"]}},"required":["mx","spf","dmarc","dkim","mta_sts"]},"fixes":{"type":"array","items":{"type":"object","properties":{"area":{"type":"string","enum":["mx","spf","dmarc","dkim","mta_sts"]},"priority":{"type":"string","enum":["high","medium","low"]},"instruction":{"type":"string"}},"required":["area","priority","instruction"]}}},"required":["domain","score","grade","checks","fixes"]},"EmailDnsRequest":{"type":"object","properties":{"domain":{"type":"string","minLength":3,"maxLength":253,"example":"tinplate.dev","description":"Domain name or email address to audit (e.g. 'tinplate.dev' or 'hello@tinplate.dev')."},"dkim_selectors":{"type":"array","items":{"type":"string","minLength":1,"maxLength":63},"maxItems":10,"example":["google","selector1","default"],"description":"Optional custom DKIM selectors to probe in addition to common defaults."}},"required":["domain"]},"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"},"ms":{"type":"integer","minimum":0},"version":{"type":"string","example":"1.0.0"}}},"ErrorEnvelope":{"type":"object","required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Request body failed validation"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"parameters":{}},"paths":{"/v1/email-dns":{"post":{"tags":["06_EMAIL_DNS"],"summary":"Audit domain email DNS deliverability (MX, SPF, DKIM, DMARC, MTA-STS)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDnsRequest"}}}},"responses":{"200":{"description":"Email DNS audit report","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/EmailDnsResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}