{"openapi":"3.1.0","info":{"title":"SSIG Mail Security Check API","version":"1.0.0","description":"Public, keyless, rate-limited API for scanning email security DNS and HTTPS signals. Rate limit: 30 requests per IP per 1 hour. Cache hits count toward the rate limit. No authentication.","contact":{"name":"SSIG-IT GmbH","email":"info@ssig-it.com","url":"https://mailcheck.ssig-it.com"},"license":{"name":"API usage terms: fair-use, no republishing as a service."}},"servers":[{"url":"https://mailcheck.ssig-it.com"}],"paths":{"/api/v1/check/{domain}":{"get":{"summary":"Run a mail security check on a domain.","description":"Returns SPF, DKIM, DMARC, MTA-STS, TLS-RPT, DANE, DNSSEC, reverse-DNS, CAA, blacklist, IPv6 and BIMI signals plus a weighted hygiene score and BSI-TR-03182 public-DNS assessment. DKIM is heuristic. Assessment is scoped to externally visible DNS/HTTPS and is NOT a TR-03182 compliance proof.","parameters":[{"name":"domain","in":"path","required":true,"description":"Public registered domain (e.g. example.com). Punycode IDN ok. IP literals, localhost and reserved TLDs (.local, .test, ...) are rejected with 400.","schema":{"type":"string","minLength":3,"maxLength":253},"example":"example.com"}],"responses":{"200":{"description":"Check complete.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests permitted per window."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds when the window is guaranteed reset."},"X-Cache":{"schema":{"type":"string","enum":["HIT","MISS"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResponse"},"example":{"checkId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","domain":"example.com","timestamp":"2026-04-24T12:00:00.000Z","hygieneScore":85,"grade":"B","ampel":"green","publicDnsAssessment":{"externallyAssessable":true,"requirementStatus":"partially_met","assessmentLevel":"good","reasons":[],"unusedDomain":false,"disclaimer":{"de":"Diese Bewertung basiert ausschließlich auf öffentlich sichtbaren DNS- und HTTPS-Signalen.","en":"This assessment is based solely on publicly visible DNS and HTTPS signals."}},"categories":{"authentication":{"score":100,"status":"pass"},"encryption":{"score":100,"status":"pass"},"dns_security":{"score":100,"status":"pass"},"reputation":{"score":90,"status":"warn"}},"checks":[{"id":"spf","status":"pass","title":{"de":"SPF","en":"SPF"},"summary":{"de":"SPF Record korrekt konfiguriert","en":"SPF record correctly configured"},"details":{"de":"SPF Record mit -all (Hardfail) gefunden. 2 DNS-Lookups, 0 void lookups.","en":"SPF record with -all (hardfail) found. 2 DNS lookups, 0 void lookups."},"weight":9,"score":100,"category":"authentication","reason":"spf_hardfail_within_limits","records":["v=spf1 include:_spf.example.com -all"],"evidence":["lookups=2","void=0","terminator=-all"],"source":"dns","standard":"TR-03182","externallyAssessable":true}],"meta":{"durationMs":312,"checksRun":13,"checksSkipped":[],"limitations":[{"de":"DKIM kann ohne aktive Mailflow-Inspektion nicht vollständig verifiziert werden.","en":"DKIM cannot be fully verified without active mailflow inspection."}]}}}}},"400":{"description":"Invalid domain input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window is guaranteed reset."},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Check failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_domain","rate_limited","check_failed"]},"message":{"type":"string"},"retryAfterSeconds":{"type":"integer","nullable":true}}},"CheckResult":{"type":"object","required":["id","status","score","weight","category","title","summary","details"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pass","warn","fail","info","error","not_assessable"]},"score":{"type":"integer","minimum":0,"maximum":100},"weight":{"type":"number"},"category":{"type":"string","enum":["authentication","encryption","dns_security","reputation"]},"title":{"$ref":"#/components/schemas/LocalizedText"},"summary":{"$ref":"#/components/schemas/LocalizedText"},"details":{"$ref":"#/components/schemas/LocalizedText"},"fix":{"$ref":"#/components/schemas/LocalizedText"},"records":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"},"source":{"type":"string","enum":["dns","https","heuristic"]},"standard":{"type":"string"},"externallyAssessable":{"type":"boolean"},"bsiRef":{"type":"string"}}},"LocalizedText":{"type":"object","required":["de","en"],"properties":{"de":{"type":"string"},"en":{"type":"string"}}},"PublicDnsAssessment":{"type":"object","required":["externallyAssessable","requirementStatus","assessmentLevel","reasons","unusedDomain","disclaimer"],"properties":{"externallyAssessable":{"type":"boolean"},"requirementStatus":{"type":"string","enum":["met","partially_met","not_met","not_assessable"]},"assessmentLevel":{"type":"string","enum":["good","acceptable","insufficient","unused_domain_protected","unknown"]},"reasons":{"type":"array","items":{"type":"string"}},"unusedDomain":{"type":"boolean"},"disclaimer":{"$ref":"#/components/schemas/LocalizedText"}}},"CheckResponse":{"type":"object","required":["checkId","domain","timestamp","hygieneScore","grade","ampel","publicDnsAssessment","categories","checks","meta"],"properties":{"checkId":{"type":"string","format":"uuid"},"domain":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"hygieneScore":{"type":"integer","minimum":0,"maximum":100},"grade":{"type":"string","enum":["A","B","C","D","F"]},"ampel":{"type":"string","enum":["green","yellow","red"]},"publicDnsAssessment":{"$ref":"#/components/schemas/PublicDnsAssessment"},"categories":{"type":"object","additionalProperties":{"type":"object","properties":{"score":{"type":"integer"},"status":{"type":"string"}}}},"checks":{"type":"array","items":{"$ref":"#/components/schemas/CheckResult"}},"meta":{"type":"object","properties":{"durationMs":{"type":"integer"},"checksRun":{"type":"integer"},"checksSkipped":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"$ref":"#/components/schemas/LocalizedText"}}}}}}}}}