{"openapi":"3.1.0","info":{"title":"DMARCLoop API","version":"1","description":"Read reporting, adviser and mail-security data and manage domains and records. Authenticate with an organization API key: `Authorization: Bearer <key>`. A key acts with the role it was created with; a partner's admin key also reaches its clients. Errors are `{ \"error\": \"<code>\" }`. The same operations are tools on the MCP server at `/mcp`."},"servers":[{"url":"https://demo.dmarcloop.com/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"responses":{"Error":{"description":"An error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/key":{"get":{"operationId":"get_key","summary":"The calling key: its organization, role, and the client organizations it reaches. Call this first: every other operation takes an orgId.","tags":["Keys"],"parameters":[],"x-permission":"org.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"keyId":{"description":"null when the caller is an app the person authorized.","type":["string","null"]},"orgId":{"type":"string"},"role":{"type":"string","description":"readonly, analyst or admin for a key; the person's role for an app."},"clients":{"type":"array","items":{"type":"object","properties":{"orgId":{"type":"string"},"name":{"type":"string"}},"required":["orgId","name"],"additionalProperties":{}}}},"required":["keyId","orgId","role","clients"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/clients":{"get":{"operationId":"list_clients","summary":"A partner's client organizations.","tags":["Organizations"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"clients.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"clients":{"type":"array","items":{"type":"object","properties":{"orgId":{"type":"string"},"name":{"type":"string"},"slug":{"type":["string","null"]}},"required":["orgId","name","slug"],"additionalProperties":{}}}},"required":["clients"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/report-addresses":{"get":{"operationId":"get_report_addresses","summary":"The organization's DMARC aggregate, failure and TLS report addresses.","tags":["Organizations"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reportDomain":{"type":"string"},"addresses":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["rua","ruf","tls"]},"address":{"type":"string"}},"required":["type","address"],"additionalProperties":{}}}},"required":["reportDomain","addresses"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/board":{"get":{"operationId":"get_board","summary":"Every domain's adviser stage, blockers, days in stage and pass rate, in one call: the organization's and, for a partner's admin key, its clients'. Start here to find what needs attention.","tags":["Adviser"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"object","properties":{"orgId":{"type":"string"},"orgName":{"type":"string"},"domainId":{"type":"string"},"domain":{"type":"string"},"stage":{"anyOf":[{"type":"string","enum":["discover","fix_sources","quarantine","reject","maintain"]},{"type":"null"}],"description":"null until the domain's first assessment."},"recommendation":{"anyOf":[{"type":"string","enum":["no_record","fix_record","keep_monitoring","resolve_sources","test_quarantine","enforce_quarantine","test_reject","enforce_reject","fully_enforcing","mail_affected"]},{"type":"null"}]},"label":{"type":["string","null"]},"blockers":{"type":"array","items":{"type":"string"}},"daysInStage":{"type":["number","null"]},"passRate":{"description":"0 to 100, one decimal; null with no mail.","type":["number","null"]}},"required":["orgId","orgName","domainId","domain","stage","recommendation","label","blockers","daysInStage","passRate"],"additionalProperties":{}}}},"required":["domains"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains":{"get":{"operationId":"list_domains","summary":"Domains, each with its totals and daily series for the window.","tags":["Domains"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","description":"The reporting window: 7, 30 or 90 days ending today (UTC). Default 30. Ignored when `from` and `to` are given.","schema":{"type":"integer","enum":[7,30,90],"default":30},"in":"query","required":false},{"name":"from","description":"The first day of a range (YYYY-MM-DD, UTC, inclusive), with `to`. At most 90 days, ending no later than today.","schema":{"type":"string","format":"date"},"in":"query","required":false},{"name":"to","description":"The last day of a range (YYYY-MM-DD, UTC, inclusive), with `from`.","schema":{"type":"string","format":"date"},"in":"query","required":false}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"from":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"to":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"domains":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Lower case, no trailing dot."},"groupName":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"sendsMail":{"type":["boolean","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."},"dns":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi"]},"mode":{"type":"string"},"status":{"type":"string"}},"required":["type","mode","status"],"additionalProperties":{}}},"stats":{"anyOf":[{"type":"object","properties":{"messages":{"type":"number"},"passing":{"type":"number"},"compliance":{"description":"0 to 100, one decimal; null with no mail.","type":["number","null"]},"unknown":{"type":"object","properties":{"sources":{"type":"number"},"messages":{"type":"number"}},"required":["sources","messages"],"additionalProperties":{},"description":"Sources not recognised and failing DMARC: a sender not set up yet, or spoofing."},"series":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"messages":{"type":"number"},"passing":{"type":"number"}},"required":["day","messages","passing"],"additionalProperties":{}}}},"required":["messages","passing","compliance","unknown","series"],"additionalProperties":{}},{"type":"null"}],"description":"null for a role that can't read reports."}},"required":["id","name","groupName","tags","sendsMail","createdAt","dns","stats"],"additionalProperties":{}}},"discovered":{"type":"array","items":{"type":"object","properties":{"policyDomain":{"type":"string"},"messages":{"type":"number"}},"required":["policyDomain","messages"],"additionalProperties":{}},"description":"Domains reports arrived for that aren't registered here."}},"required":["days","from","to","domains","discovered"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"add_domain","summary":"Add a domain.","tags":["Domains"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"example.com"},"groupName":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}}}}}}},"x-permission":"domains.write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Lower case, no trailing dot."},"groupName":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"sendsMail":{"type":["boolean","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","name","groupName","tags","sendsMail","createdAt"],"additionalProperties":{}}},"required":["domain"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}":{"get":{"operationId":"get_domain_overview","summary":"A domain's overview: totals, daily series, published policy and its changes.","tags":["Reporting"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","description":"The reporting window: 7, 30 or 90 days ending today (UTC). Default 30. Ignored when `from` and `to` are given.","schema":{"type":"integer","enum":[7,30,90],"default":30},"in":"query","required":false},{"name":"from","description":"The first day of a range (YYYY-MM-DD, UTC, inclusive), with `to`. At most 90 days, ending no later than today.","schema":{"type":"string","format":"date"},"in":"query","required":false},{"name":"to","description":"The last day of a range (YYYY-MM-DD, UTC, inclusive), with `from`.","schema":{"type":"string","format":"date"},"in":"query","required":false}],"x-permission":"reports.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Lower case, no trailing dot."},"groupName":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"sendsMail":{"type":["boolean","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","name","groupName","tags","sendsMail","createdAt"],"additionalProperties":{}},"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"from":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"to":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"totals":{"type":"object","properties":{"messages":{"type":"number"},"passing":{"type":"number"},"compliance":{"description":"0 to 100, one decimal; null with no mail.","type":["number","null"]},"quarantined":{"type":"number"},"rejected":{"type":"number"},"sources":{"type":"number"}},"required":["messages","passing","compliance","quarantined","rejected","sources"],"additionalProperties":{}},"series":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"messages":{"type":"number"},"passing":{"type":"number"},"quarantined":{"type":"number"},"rejected":{"type":"number"}},"required":["day","messages","passing","quarantined","rejected"],"additionalProperties":{}}},"policy":{"anyOf":[{"type":"object","properties":{"p":{"type":"string"},"label":{"type":"string"},"asOf":{"type":"string","description":"A UTC day, YYYY-MM-DD."}},"required":["p","label","asOf"],"additionalProperties":{}},{"type":"null"}],"description":"The policy receivers last saw."},"policyChanges":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"from":{"type":["string","null"]},"to":{"type":"string"}},"required":["day","from","to"],"additionalProperties":{}}},"dnsChanges":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"at":{"type":"string","description":"An ISO 8601 timestamp."},"type":{"type":"string","enum":["dmarc","spf"]},"detail":{"type":"string"},"before":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"after":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]}},"required":["day","at","type","detail","before","after"],"additionalProperties":{}},"description":"DMARC and SPF changes the DNS history saw in the range, oldest first."},"categories":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"sources":{"type":"number"},"messages":{"type":"number"}},"required":["sources","messages"],"additionalProperties":{}}},"subdomains":{"type":"array","items":{"type":"object","properties":{"headerFrom":{"type":"string"},"messages":{"type":"number"},"passing":{"type":"number"},"sources":{"type":"number"}},"required":["headerFrom","messages","passing","sources"],"additionalProperties":{}}},"reporters":{"type":"array","items":{"type":"object","properties":{"reporter":{"type":"string","description":"The receiver's name, as its reports give it."},"reports":{"type":"number"},"messages":{"type":"number"},"days":{"type":"number","description":"Distinct days it sent a report for."},"firstDay":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"lastDay":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"quiet":{"type":"boolean","description":"It reported on 3 days or more, and its last report is 3 days or more behind the domain's newest."}},"required":["reporter","reports","messages","days","firstDay","lastDay","quiet"],"additionalProperties":{}},"description":"The receivers whose aggregate reports cover the domain, most messages first."}},"required":["domain","days","from","to","totals","series","policy","policyChanges","dnsChanges","categories","subdomains","reporters"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/sources":{"get":{"operationId":"list_sources","summary":"Every sending source for the domain, classified, busiest first.","tags":["Reporting"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","description":"The reporting window: 7, 30 or 90 days ending today (UTC). Default 30. Ignored when `from` and `to` are given.","schema":{"type":"integer","enum":[7,30,90],"default":30},"in":"query","required":false},{"name":"from","description":"The first day of a range (YYYY-MM-DD, UTC, inclusive), with `to`. At most 90 days, ending no later than today.","schema":{"type":"string","format":"date"},"in":"query","required":false},{"name":"to","description":"The last day of a range (YYYY-MM-DD, UTC, inclusive), with `from`.","schema":{"type":"string","format":"date"},"in":"query","required":false}],"x-permission":"reports.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Lower case, no trailing dot."},"groupName":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"sendsMail":{"type":["boolean","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","name","groupName","tags","sendsMail","createdAt"],"additionalProperties":{}},"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"from":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"to":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"sources":{"type":"array","items":{"type":"object","properties":{"ip":{"type":"string"},"messages":{"type":"number"},"passing":{"type":"number"},"dkimAligned":{"type":"number"},"spfAligned":{"type":"number"},"forwardOverride":{"type":"number","description":"Messages receivers overrode as forwarded."},"spfFailDkimPass":{"type":"number"},"rejected":{"type":"number"},"quarantined":{"type":"number"},"reporters":{"type":"number"},"ptr":{"type":["string","null"]},"asn":{"type":["number","null"]},"asName":{"type":["string","null"]},"country":{"type":["string","null"]},"senderId":{"type":["string","null"]},"compliance":{"description":"0 to 100, one decimal; null with no mail.","type":["number","null"]},"category":{"type":"string","description":"The source's classification, e.g. known, forwarded, unknown."},"sender":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"}},"required":["id","name","category"],"additionalProperties":{}},{"type":"null"}]}},"required":["ip","messages","passing","dkimAligned","spfAligned","forwardOverride","spfFailDkimPass","rejected","quarantined","reporters","ptr","asn","asName","country","senderId","compliance","category","sender"],"additionalProperties":{}}}},"required":["domain","days","from","to","sources"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/sources/{ip}":{"get":{"operationId":"get_source","summary":"One source IP: its results by reporter and authentication, and its raw report rows.","tags":["Reporting"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}},{"name":"ip","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","description":"The reporting window: 7, 30 or 90 days ending today (UTC). Default 30. Ignored when `from` and `to` are given.","schema":{"type":"integer","enum":[7,30,90],"default":30},"in":"query","required":false},{"name":"from","description":"The first day of a range (YYYY-MM-DD, UTC, inclusive), with `to`. At most 90 days, ending no later than today.","schema":{"type":"string","format":"date"},"in":"query","required":false},{"name":"to","description":"The last day of a range (YYYY-MM-DD, UTC, inclusive), with `from`.","schema":{"type":"string","format":"date"},"in":"query","required":false}],"x-permission":"reports.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Lower case, no trailing dot."},"groupName":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"sendsMail":{"type":["boolean","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","name","groupName","tags","sendsMail","createdAt"],"additionalProperties":{}},"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"from":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"to":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"source":{"type":"object","properties":{"ip":{"type":"string"},"messages":{"type":"number"},"passing":{"type":"number"},"dkimAligned":{"type":"number"},"spfAligned":{"type":"number"},"forwardOverride":{"type":"number","description":"Messages receivers overrode as forwarded."},"spfFailDkimPass":{"type":"number"},"rejected":{"type":"number"},"quarantined":{"type":"number"},"reporters":{"type":"number"},"ptr":{"type":["string","null"]},"asn":{"type":["number","null"]},"asName":{"type":["string","null"]},"country":{"type":["string","null"]},"senderId":{"type":["string","null"]},"compliance":{"description":"0 to 100, one decimal; null with no mail.","type":["number","null"]},"category":{"type":"string","description":"The source's classification, e.g. known, forwarded, unknown."}},"required":["ip","messages","passing","dkimAligned","spfAligned","forwardOverride","spfFailDkimPass","rejected","quarantined","reporters","ptr","asn","asName","country","senderId","compliance","category"],"additionalProperties":{}},"enrichment":{"anyOf":[{"type":"object","properties":{"ip":{"type":"string"},"ptr":{"type":["string","null"]},"authDomains":{"type":"array","items":{"type":"string"}},"firstSeen":{"type":"string"},"lastSeen":{"type":"string"}},"required":["ip","ptr","authDomains","firstSeen","lastSeen"],"additionalProperties":{}},{"type":"null"}]},"sender":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":{}},{"type":"null"}]},"breakdown":{"type":"array","items":{"type":"object","properties":{"headerFrom":{"type":"string"},"reporter":{"type":"string"},"spfResult":{"type":"string"},"spfAligned":{"type":"boolean"},"dkimResult":{"type":"string"},"dkimAligned":{"type":"boolean"},"disposition":{"type":"string"},"override":{"type":["string","null"]},"messages":{"type":"number"}},"required":["headerFrom","reporter","spfResult","spfAligned","dkimResult","dkimAligned","disposition","override","messages"],"additionalProperties":{}}},"raw":{"type":"array","items":{"type":"object","properties":{"reportId":{"type":"string"},"reporter":{"type":"string"},"day":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"headerFrom":{"type":"string"},"envelopeFrom":{"type":["string","null"]},"spfDomain":{"type":["string","null"]},"spfResult":{"type":"string"},"dkimDomain":{"type":["string","null"]},"dkimSelector":{"type":["string","null"]},"dkimResult":{"type":"string"},"disposition":{"type":"string"},"count":{"type":"number"}},"required":["reportId","reporter","day","headerFrom","envelopeFrom","spfDomain","spfResult","dkimDomain","dkimSelector","dkimResult","disposition","count"],"additionalProperties":{}},"description":"The latest 200 report rows."}},"required":["domain","days","from","to","source","enrichment","sender","breakdown","raw"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/adviser":{"get":{"operationId":"get_adviser","summary":"The reject adviser's assessment: stage, next step, blockers, tasks and what the next step would affect.","tags":["Adviser"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"reports.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"adviser":{"type":"object","properties":{"stage":{"type":"string","enum":["discover","fix_sources","quarantine","reject","maintain"]},"stageLabel":{"type":"string"},"recommendation":{"type":"string","enum":["no_record","fix_record","keep_monitoring","resolve_sources","test_quarantine","enforce_quarantine","test_reject","enforce_reject","fully_enforcing","mail_affected"]},"label":{"type":"string","description":"The Next step panel's heading."},"policy":{"type":["string","null"]},"policyPresent":{"type":"boolean"},"daysInStage":{"type":"number"},"daysCovered":{"type":"number"},"messages":{"type":"number"},"passRate":{"description":"0 to 100, one decimal; null with no mail.","type":["number","null"]},"blockers":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"text":{"type":"string"},"ip":{"type":"string"}},"required":["kind","text"],"additionalProperties":{}}},"tasks":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"ip":{"type":"string"},"record":{"description":"The exact record to publish.","type":"string"},"sender":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":{}},{"type":"null"}]}},"required":["text","sender"],"additionalProperties":{}}},"next":{"anyOf":[{"type":"object","properties":{"p":{"type":"string"},"sp":{"type":"string"},"np":{"type":"string"},"adkim":{"type":"string"},"aspf":{"type":"string"},"t":{"type":"boolean"},"rua":{"type":"array","items":{"type":"string"}},"ruf":{"type":"array","items":{"type":"string"}}},"required":["p","rua","ruf"],"additionalProperties":{},"description":"A DMARC record's configuration."},{"type":"null"}],"description":"The record for the recommended step."},"stepBack":{"anyOf":[{"type":"object","properties":{"p":{"type":"string"},"sp":{"type":"string"},"np":{"type":"string"},"adkim":{"type":"string"},"aspf":{"type":"string"},"t":{"type":"boolean"},"rua":{"type":"array","items":{"type":"string"}},"ruf":{"type":"array","items":{"type":"string"}}},"required":["p","rua","ruf"],"additionalProperties":{},"description":"A DMARC record's configuration."},{"type":"null"}],"description":"While mail is affected: the step back."},"simulation":{"type":"object","properties":{"affected":{"type":"number","description":"Messages that would have failed under the next step."},"legitimate":{"type":"number"},"sources":{"type":"array","items":{"type":"object","properties":{"ip":{"type":"string"},"failing":{"type":"number"},"sender":{"type":["string","null"]}},"required":["ip","failing","sender"],"additionalProperties":{}}}},"required":["affected","legitimate","sources"],"additionalProperties":{}},"suggestLockdown":{"type":"boolean"},"computedAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["stage","stageLabel","recommendation","label","policy","policyPresent","daysInStage","daysCovered","messages","passRate","blockers","tasks","next","stepBack","simulation","suggestLockdown","computedAt"],"additionalProperties":{}},"hostedDmarc":{"type":"boolean"},"policyChange":{"anyOf":[{"type":"object","properties":{"at":{"type":"string","description":"An ISO 8601 timestamp."},"move":{"type":"string","enum":["tightened","loosened"]},"from":{"type":"string"},"to":{"type":"string"}},"required":["at","move","from","to"],"additionalProperties":{}},{"type":"null"}],"description":"The latest DMARC policy change made at the DNS provider in the last 30 days; null for a hosted record."}},"required":["adviser","hostedDmarc","policyChange"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/adviser/refresh":{"post":{"operationId":"refresh_adviser","summary":"Re-read the domain's DNS and reassess now, after a record changed.","tags":["Adviser"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"reports.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"adviser":{"type":"object","properties":{"stage":{"type":"string","enum":["discover","fix_sources","quarantine","reject","maintain"]},"stageLabel":{"type":"string"},"recommendation":{"type":"string","enum":["no_record","fix_record","keep_monitoring","resolve_sources","test_quarantine","enforce_quarantine","test_reject","enforce_reject","fully_enforcing","mail_affected"]},"label":{"type":"string","description":"The Next step panel's heading."},"policy":{"type":["string","null"]},"policyPresent":{"type":"boolean"},"daysInStage":{"type":"number"},"daysCovered":{"type":"number"},"messages":{"type":"number"},"passRate":{"description":"0 to 100, one decimal; null with no mail.","type":["number","null"]},"blockers":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"text":{"type":"string"},"ip":{"type":"string"}},"required":["kind","text"],"additionalProperties":{}}},"tasks":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"ip":{"type":"string"},"record":{"description":"The exact record to publish.","type":"string"},"sender":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":{}},{"type":"null"}]}},"required":["text","sender"],"additionalProperties":{}}},"next":{"anyOf":[{"type":"object","properties":{"p":{"type":"string"},"sp":{"type":"string"},"np":{"type":"string"},"adkim":{"type":"string"},"aspf":{"type":"string"},"t":{"type":"boolean"},"rua":{"type":"array","items":{"type":"string"}},"ruf":{"type":"array","items":{"type":"string"}}},"required":["p","rua","ruf"],"additionalProperties":{},"description":"A DMARC record's configuration."},{"type":"null"}],"description":"The record for the recommended step."},"stepBack":{"anyOf":[{"type":"object","properties":{"p":{"type":"string"},"sp":{"type":"string"},"np":{"type":"string"},"adkim":{"type":"string"},"aspf":{"type":"string"},"t":{"type":"boolean"},"rua":{"type":"array","items":{"type":"string"}},"ruf":{"type":"array","items":{"type":"string"}}},"required":["p","rua","ruf"],"additionalProperties":{},"description":"A DMARC record's configuration."},{"type":"null"}],"description":"While mail is affected: the step back."},"simulation":{"type":"object","properties":{"affected":{"type":"number","description":"Messages that would have failed under the next step."},"legitimate":{"type":"number"},"sources":{"type":"array","items":{"type":"object","properties":{"ip":{"type":"string"},"failing":{"type":"number"},"sender":{"type":["string","null"]}},"required":["ip","failing","sender"],"additionalProperties":{}}}},"required":["affected","legitimate","sources"],"additionalProperties":{}},"suggestLockdown":{"type":"boolean"},"computedAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["stage","stageLabel","recommendation","label","policy","policyPresent","daysInStage","daysCovered","messages","passRate","blockers","tasks","next","stepBack","simulation","suggestLockdown","computedAt"],"additionalProperties":{}}},"required":["adviser"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/dns":{"get":{"operationId":"get_dns_records","summary":"The domain's managed records (DMARC, SPF, TLS-RPT, DKIM, BIMI) and their checks.","tags":["DNS"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Lower case, no trailing dot."},"groupName":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"sendsMail":{"type":["boolean","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","name","groupName","tags","sendsMail","createdAt"],"additionalProperties":{}},"liveDmarc":{"anyOf":[{"type":"object","properties":{"records":{"type":"array","items":{"type":"string"},"description":"The DMARC records DNS answered."},"valid":{"type":"boolean"},"reportsHere":{"type":"boolean","description":"Whether the record's rua includes reportAddress."}},"required":["records","valid","reportsHere"],"additionalProperties":{}},{"type":"null"}],"description":"With no DMARC record set up here: what _dmarc publishes now, read live."},"hostingAvailable":{"type":"boolean"},"reportAddress":{"type":"string"},"tlsAddress":{"type":"string"},"zone":{"type":["string","null"]},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi"]},"mode":{"type":"string","enum":["hosted","self"]},"config":{"type":"object","properties":{},"additionalProperties":{}},"version":{"type":"number"},"issues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"lookups":{"type":["number","null"]},"status":{"type":"string","enum":["pending","ok","missing","mismatch","error"]},"observed":{"description":"What DNS answered at the last check.","type":["string","null"]},"detail":{"type":["string","null"]},"checkedAt":{"anyOf":[{"type":"string","description":"An ISO 8601 timestamp."},{"type":"null"}]},"customers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Fully qualified."},"type":{"type":"string","enum":["CNAME","TXT","MX"]},"value":{"type":"string"},"purpose":{"type":"string"}},"required":["name","type","value","purpose"],"additionalProperties":{},"description":"A record the customer publishes in their own DNS."}}},"required":["type","mode","config","version","issues","lookups","status","observed","detail","checkedAt","customers"],"additionalProperties":{}}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi","mx","mtasts"]},"kind":{"type":"string","description":"observed (first read), changed, verified, broken, published, resolved (SPF re-resolve) or removed."},"detail":{"type":"string"},"name":{"description":"The DNS name read; set on the watcher's entries only.","type":["string","null"]},"before":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"after":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","type","kind","detail","name","before","after","createdAt"],"additionalProperties":{}}}},"required":["domain","liveDmarc","hostingAvailable","reportAddress","tlsAddress","zone","records","events"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/dns/{type}/preview":{"post":{"operationId":"preview_dns_record","summary":"What publishing a record would do, without saving it: the records to publish, what we'd host, and any issues. `type` is dmarc, spf, tlsrpt, dkim or bimi.","tags":["DNS"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mode","config"],"properties":{"mode":{"type":"string","enum":["hosted","self"],"description":"hosted: we serve it and you publish a CNAME; self: you publish the record."},"config":{"description":"The record type's configuration: the schema matching the path's `type`.","anyOf":[{"title":"dmarc","type":"object","properties":{"p":{"type":"string","enum":["none","quarantine","reject"]},"sp":{"type":"string","enum":["none","quarantine","reject"]},"np":{"type":"string","enum":["none","quarantine","reject"]},"adkim":{"type":"string","enum":["r","s"]},"aspf":{"type":"string","enum":["r","s"]},"t":{"type":"boolean"},"psd":{"type":"string","enum":["y","n","u"]},"rua":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"ruf":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"fo":{"type":"string","pattern":"^[01ds](:[01ds])*$"}},"required":["p","rua","ruf"]},{"title":"spf","type":"object","properties":{"sources":{"maxItems":40,"type":"array","items":{"type":"string","minLength":1,"maxLength":255}},"flatten":{"type":"boolean"},"all":{"type":"string","enum":["-all","~all"]}},"required":["sources","flatten","all"]},{"title":"tlsrpt","type":"object","properties":{"rua":{"maxItems":5,"type":"array","items":{"anyOf":[{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"string","maxLength":512,"format":"uri"}]}}},"required":["rua"]},{"title":"dkim","type":"object","properties":{"selectors":{"minItems":1,"maxItems":20,"type":"array","items":{"oneOf":[{"type":"object","properties":{"selector":{"type":"string"},"kind":{"type":"string","const":"txt"},"value":{"type":"string","minLength":1,"maxLength":2048}},"required":["selector","kind","value"]},{"type":"object","properties":{"selector":{"type":"string"},"kind":{"type":"string","const":"cname"},"value":{"type":"string","maxLength":253,"pattern":"^(?!-)[a-z0-9-_]{1,63}(?:\\.(?!-)[a-z0-9-_]{1,63})+\\.?$"}},"required":["selector","kind","value"]}]}}},"required":["selectors"]},{"title":"bimi","type":"object","properties":{"logoUrl":{"type":"string","maxLength":512,"format":"uri"},"authorityUrl":{"anyOf":[{"type":"string","maxLength":512,"format":"uri"},{"type":"null"}]}},"required":["logoUrl","authorityUrl"]}]}}}}}},"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"object","properties":{"customers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Fully qualified."},"type":{"type":"string","enum":["CNAME","TXT","MX"]},"value":{"type":"string"},"purpose":{"type":"string"}},"required":["name","type","value","purpose"],"additionalProperties":{},"description":"A record the customer publishes in their own DNS."}},"pool":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"content":{"type":"string"}},"required":["name","content"],"additionalProperties":{}},"description":"What we would host, for a hosted record."},"issues":{"type":"array","items":{"type":"string"},"description":"Problems that stop it publishing."},"warnings":{"type":"array","items":{"type":"string"}},"lookups":{"type":["number","null"]}},"required":["customers","pool","issues","warnings","lookups"],"additionalProperties":{}},"assigned":{"type":"boolean","description":"false: the domain has no pool zone yet, so names are a shape."}},"required":["plan","assigned"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/dns/{type}":{"put":{"operationId":"publish_dns_record","summary":"Publish a record as a new version: hosted or self-managed. `type` is dmarc, spf, tlsrpt, dkim or bimi. Preview it first.","tags":["DNS"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mode","config"],"properties":{"mode":{"type":"string","enum":["hosted","self"],"description":"hosted: we serve it and you publish a CNAME; self: you publish the record."},"config":{"description":"The record type's configuration: the schema matching the path's `type`.","anyOf":[{"title":"dmarc","type":"object","properties":{"p":{"type":"string","enum":["none","quarantine","reject"]},"sp":{"type":"string","enum":["none","quarantine","reject"]},"np":{"type":"string","enum":["none","quarantine","reject"]},"adkim":{"type":"string","enum":["r","s"]},"aspf":{"type":"string","enum":["r","s"]},"t":{"type":"boolean"},"psd":{"type":"string","enum":["y","n","u"]},"rua":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"ruf":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"fo":{"type":"string","pattern":"^[01ds](:[01ds])*$"}},"required":["p","rua","ruf"]},{"title":"spf","type":"object","properties":{"sources":{"maxItems":40,"type":"array","items":{"type":"string","minLength":1,"maxLength":255}},"flatten":{"type":"boolean"},"all":{"type":"string","enum":["-all","~all"]}},"required":["sources","flatten","all"]},{"title":"tlsrpt","type":"object","properties":{"rua":{"maxItems":5,"type":"array","items":{"anyOf":[{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"string","maxLength":512,"format":"uri"}]}}},"required":["rua"]},{"title":"dkim","type":"object","properties":{"selectors":{"minItems":1,"maxItems":20,"type":"array","items":{"oneOf":[{"type":"object","properties":{"selector":{"type":"string"},"kind":{"type":"string","const":"txt"},"value":{"type":"string","minLength":1,"maxLength":2048}},"required":["selector","kind","value"]},{"type":"object","properties":{"selector":{"type":"string"},"kind":{"type":"string","const":"cname"},"value":{"type":"string","maxLength":253,"pattern":"^(?!-)[a-z0-9-_]{1,63}(?:\\.(?!-)[a-z0-9-_]{1,63})+\\.?$"}},"required":["selector","kind","value"]}]}}},"required":["selectors"]},{"title":"bimi","type":"object","properties":{"logoUrl":{"type":"string","maxLength":512,"format":"uri"},"authorityUrl":{"anyOf":[{"type":"string","maxLength":512,"format":"uri"},{"type":"null"}]}},"required":["logoUrl","authorityUrl"]}]}}}}}},"x-permission":"dns.write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Lower case, no trailing dot."},"groupName":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"sendsMail":{"type":["boolean","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","name","groupName","tags","sendsMail","createdAt"],"additionalProperties":{}},"liveDmarc":{"anyOf":[{"type":"object","properties":{"records":{"type":"array","items":{"type":"string"},"description":"The DMARC records DNS answered."},"valid":{"type":"boolean"},"reportsHere":{"type":"boolean","description":"Whether the record's rua includes reportAddress."}},"required":["records","valid","reportsHere"],"additionalProperties":{}},{"type":"null"}],"description":"With no DMARC record set up here: what _dmarc publishes now, read live."},"hostingAvailable":{"type":"boolean"},"reportAddress":{"type":"string"},"tlsAddress":{"type":"string"},"zone":{"type":["string","null"]},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi"]},"mode":{"type":"string","enum":["hosted","self"]},"config":{"type":"object","properties":{},"additionalProperties":{}},"version":{"type":"number"},"issues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"lookups":{"type":["number","null"]},"status":{"type":"string","enum":["pending","ok","missing","mismatch","error"]},"observed":{"description":"What DNS answered at the last check.","type":["string","null"]},"detail":{"type":["string","null"]},"checkedAt":{"anyOf":[{"type":"string","description":"An ISO 8601 timestamp."},{"type":"null"}]},"customers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Fully qualified."},"type":{"type":"string","enum":["CNAME","TXT","MX"]},"value":{"type":"string"},"purpose":{"type":"string"}},"required":["name","type","value","purpose"],"additionalProperties":{},"description":"A record the customer publishes in their own DNS."}}},"required":["type","mode","config","version","issues","lookups","status","observed","detail","checkedAt","customers"],"additionalProperties":{}}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi","mx","mtasts"]},"kind":{"type":"string","description":"observed (first read), changed, verified, broken, published, resolved (SPF re-resolve) or removed."},"detail":{"type":"string"},"name":{"description":"The DNS name read; set on the watcher's entries only.","type":["string","null"]},"before":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"after":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","type","kind","detail","name","before","after","createdAt"],"additionalProperties":{}}}},"required":["domain","liveDmarc","hostingAvailable","reportAddress","tlsAddress","zone","records","events"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/dns/{type}/versions":{"get":{"operationId":"list_dns_record_versions","summary":"A record's published versions, newest first: what rollback can return to.","tags":["DNS"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"object","properties":{"version":{"type":"number"},"mode":{"type":"string","enum":["hosted","self"]},"config":{"type":"object","properties":{},"additionalProperties":{}},"reason":{"type":"string"},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["version","mode","config","reason","createdAt"],"additionalProperties":{}}}},"required":["versions"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/dns/{type}/rollback":{"post":{"operationId":"rollback_dns_record","summary":"Republish an earlier version of a record as a new version.","tags":["DNS"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["version"],"properties":{"version":{"type":"integer","minimum":1}}}}}},"x-permission":"dns.write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Lower case, no trailing dot."},"groupName":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"sendsMail":{"type":["boolean","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","name","groupName","tags","sendsMail","createdAt"],"additionalProperties":{}},"liveDmarc":{"anyOf":[{"type":"object","properties":{"records":{"type":"array","items":{"type":"string"},"description":"The DMARC records DNS answered."},"valid":{"type":"boolean"},"reportsHere":{"type":"boolean","description":"Whether the record's rua includes reportAddress."}},"required":["records","valid","reportsHere"],"additionalProperties":{}},{"type":"null"}],"description":"With no DMARC record set up here: what _dmarc publishes now, read live."},"hostingAvailable":{"type":"boolean"},"reportAddress":{"type":"string"},"tlsAddress":{"type":"string"},"zone":{"type":["string","null"]},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi"]},"mode":{"type":"string","enum":["hosted","self"]},"config":{"type":"object","properties":{},"additionalProperties":{}},"version":{"type":"number"},"issues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"lookups":{"type":["number","null"]},"status":{"type":"string","enum":["pending","ok","missing","mismatch","error"]},"observed":{"description":"What DNS answered at the last check.","type":["string","null"]},"detail":{"type":["string","null"]},"checkedAt":{"anyOf":[{"type":"string","description":"An ISO 8601 timestamp."},{"type":"null"}]},"customers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Fully qualified."},"type":{"type":"string","enum":["CNAME","TXT","MX"]},"value":{"type":"string"},"purpose":{"type":"string"}},"required":["name","type","value","purpose"],"additionalProperties":{},"description":"A record the customer publishes in their own DNS."}}},"required":["type","mode","config","version","issues","lookups","status","observed","detail","checkedAt","customers"],"additionalProperties":{}}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi","mx","mtasts"]},"kind":{"type":"string","description":"observed (first read), changed, verified, broken, published, resolved (SPF re-resolve) or removed."},"detail":{"type":"string"},"name":{"description":"The DNS name read; set on the watcher's entries only.","type":["string","null"]},"before":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"after":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","type","kind","detail","name","before","after","createdAt"],"additionalProperties":{}}}},"required":["domain","liveDmarc","hostingAvailable","reportAddress","tlsAddress","zone","records","events"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/dns/history":{"get":{"operationId":"get_dns_history","summary":"The domain's DNS history, newest first: each record's value changes with before and after, and status changes and publishes. DMARC and SPF are read hourly, MX, MTA-STS, TLS-RPT and BIMI every six hours.","tags":["DNS"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","description":"Comma-separated record types: dmarc, spf, mx, mtasts, tlsrpt, dkim, bimi. Default all.","schema":{"type":"string"},"in":"query","required":false},{"name":"kind","description":"Comma-separated kinds: observed, changed, verified, broken, published, resolved, removed. Default all.","schema":{"type":"string"},"in":"query","required":false},{"name":"from","description":"The first day (YYYY-MM-DD, UTC, inclusive).","schema":{"type":"string","format":"date"},"in":"query","required":false},{"name":"to","description":"The last day (YYYY-MM-DD, UTC, inclusive).","schema":{"type":"string","format":"date"},"in":"query","required":false},{"name":"limit","description":"Entries to return, 1 to 500. Default 100.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","required":false}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi","mx","mtasts"]},"kind":{"type":"string","description":"observed (first read), changed, verified, broken, published, resolved (SPF re-resolve) or removed."},"detail":{"type":"string"},"name":{"description":"The DNS name read; set on the watcher's entries only.","type":["string","null"]},"before":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"after":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","type","kind","detail","name","before","after","createdAt"],"additionalProperties":{}}}},"required":["events"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/dns/snapshot":{"get":{"operationId":"get_dns_snapshot","summary":"The watched records as they stood at a moment: each one's value then and since when. Only covers what was read from when monitoring started; it restores nothing.","tags":["DNS"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}},{"name":"at","description":"A UTC day (YYYY-MM-DD, meaning its end) or an ISO 8601 timestamp.","schema":{"type":"string"},"required":true,"in":"query"}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"at":{"type":"string","description":"An ISO 8601 timestamp."},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi","mx","mtasts"]},"name":{"type":"string"},"value":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"since":{"type":"string","description":"When this value was first read."}},"required":["type","name","value","since"],"additionalProperties":{}}}},"required":["at","records"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/dns/check":{"post":{"operationId":"check_dns_records","summary":"Check the domain's records in DNS now.","tags":["DNS"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Lower case, no trailing dot."},"groupName":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"sendsMail":{"type":["boolean","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","name","groupName","tags","sendsMail","createdAt"],"additionalProperties":{}},"liveDmarc":{"anyOf":[{"type":"object","properties":{"records":{"type":"array","items":{"type":"string"},"description":"The DMARC records DNS answered."},"valid":{"type":"boolean"},"reportsHere":{"type":"boolean","description":"Whether the record's rua includes reportAddress."}},"required":["records","valid","reportsHere"],"additionalProperties":{}},{"type":"null"}],"description":"With no DMARC record set up here: what _dmarc publishes now, read live."},"hostingAvailable":{"type":"boolean"},"reportAddress":{"type":"string"},"tlsAddress":{"type":"string"},"zone":{"type":["string","null"]},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi"]},"mode":{"type":"string","enum":["hosted","self"]},"config":{"type":"object","properties":{},"additionalProperties":{}},"version":{"type":"number"},"issues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"lookups":{"type":["number","null"]},"status":{"type":"string","enum":["pending","ok","missing","mismatch","error"]},"observed":{"description":"What DNS answered at the last check.","type":["string","null"]},"detail":{"type":["string","null"]},"checkedAt":{"anyOf":[{"type":"string","description":"An ISO 8601 timestamp."},{"type":"null"}]},"customers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Fully qualified."},"type":{"type":"string","enum":["CNAME","TXT","MX"]},"value":{"type":"string"},"purpose":{"type":"string"}},"required":["name","type","value","purpose"],"additionalProperties":{},"description":"A record the customer publishes in their own DNS."}}},"required":["type","mode","config","version","issues","lookups","status","observed","detail","checkedAt","customers"],"additionalProperties":{}}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["dmarc","spf","tlsrpt","dkim","bimi","mx","mtasts"]},"kind":{"type":"string","description":"observed (first read), changed, verified, broken, published, resolved (SPF re-resolve) or removed."},"detail":{"type":"string"},"name":{"description":"The DNS name read; set on the watcher's entries only.","type":["string","null"]},"before":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"after":{"description":"The record set, one record per line; null when nothing was published.","type":["string","null"]},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","type","kind","detail","name","before","after","createdAt"],"additionalProperties":{}}}},"required":["domain","liveDmarc","hostingAvailable","reportAddress","tlsAddress","zone","records","events"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/mail/tls":{"get":{"operationId":"get_tls_reports","summary":"TLS reporting (RFC 8460): sessions by day, by policy and reporter, and failures.","tags":["Mail security"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","description":"The reporting window: 7, 30 or 90 days ending today (UTC). Default 30. Ignored when `from` and `to` are given.","schema":{"type":"integer","enum":[7,30,90],"default":30},"in":"query","required":false},{"name":"from","description":"The first day of a range (YYYY-MM-DD, UTC, inclusive), with `to`. At most 90 days, ending no later than today.","schema":{"type":"string","format":"date"},"in":"query","required":false},{"name":"to","description":"The last day of a range (YYYY-MM-DD, UTC, inclusive), with `from`.","schema":{"type":"string","format":"date"},"in":"query","required":false}],"x-permission":"reports.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"entitled":{"type":"boolean","description":"false: the plan has no TLS reporting; lists are empty."},"addresses":{"type":"object","properties":{"mailto":{"type":"string"},"https":{"type":"string"}},"required":["mailto","https"],"additionalProperties":{}},"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"from":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"to":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"series":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","description":"A UTC day, YYYY-MM-DD."},"successful":{"type":"number"},"failed":{"type":"number"}},"required":["day","successful","failed"],"additionalProperties":{}}},"policies":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"reporter":{"type":"string"},"reports":{"type":"number"},"successful":{"type":"number"},"failed":{"type":"number"},"lastDay":{"type":"string","description":"A UTC day, YYYY-MM-DD."}},"required":["type","reporter","reports","successful","failed","lastDay"],"additionalProperties":{}}},"failures":{"type":"array","items":{"type":"object","properties":{"resultType":{"type":"string"},"receivingMx":{"type":["string","null"]},"failed":{"type":"number"},"senders":{"type":"number"},"lastDay":{"type":"string","description":"A UTC day, YYYY-MM-DD."}},"required":["resultType","receivingMx","failed","senders","lastDay"],"additionalProperties":{}}}},"required":["entitled","addresses","series","policies","failures"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/mail/dkim":{"get":{"operationId":"list_dkim_keys","summary":"DKIM selectors seen for the domain, their keys and key ages.","tags":["Mail security"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"thresholds":{"type":"object","properties":{"rotationDays":{"type":"number"}},"required":["rotationDays"],"additionalProperties":{}},"keys":{"type":"array","items":{"type":"object","properties":{"selector":{"type":"string"},"source":{"type":"string","enum":["report","hosted","probe"]},"keyType":{"type":["string","null"]},"bits":{"type":["number","null"]},"revoked":{"type":"boolean"},"record":{"type":["string","null"]},"ageDays":{"type":["number","null"]},"rotationDue":{"type":"boolean"},"checkedAt":{"anyOf":[{"type":"string","description":"An ISO 8601 timestamp."},{"type":"null"}]}},"required":["selector","source","keyType","bits","revoked","record","ageDays","rotationDue","checkedAt"],"additionalProperties":{}}}},"required":["thresholds","keys"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/domains/{domainId}/mail/checks":{"get":{"operationId":"get_mail_checks","summary":"The latest MTA-STS and BIMI checks.","tags":["Mail security"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"checks":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"kind":{"type":"string"},"status":{"type":"string"},"checkedAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["kind","status","checkedAt"],"additionalProperties":{}},"description":"By kind: mta_sts, bimi."}},"required":["checks"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/alerts":{"get":{"operationId":"list_alerts","summary":"Active alerts and recent alert history.","tags":["Alerts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"kind":{"type":"string"},"label":{"type":"string"},"domain":{"type":["string","null"]},"domainId":{"type":["string","null"]},"raisedAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["key","kind","label","domain","domainId","raisedAt"],"additionalProperties":{}}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"domainId":{"type":["string","null"]},"title":{"type":"string"},"body":{"type":"string"},"resolved":{"type":"boolean"},"createdAt":{"type":"string","description":"An ISO 8601 timestamp."}},"required":["id","kind","domainId","title","body","resolved","createdAt"],"additionalProperties":{}}}},"required":["active","events"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/exports/{kind}.csv":{"get":{"operationId":"export_csv","summary":"A CSV export: `domains` and `sources` (with `domainId`) need reports.read, `records` domains.read, and `usage` (partners: per-client usage for the month) billing.read.","tags":["Exports"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"kind","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","description":"The reporting window: 7, 30 or 90 days ending today (UTC). Default 30. Ignored when `from` and `to` are given.","schema":{"type":"integer","enum":[7,30,90],"default":30},"in":"query","required":false},{"name":"domainId","description":"For `sources`.","schema":{"type":"string"},"in":"query","required":false}],"x-permission":"domains.read","responses":{"200":{"description":"OK","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orgs/{orgId}/exports/report.pdf":{"get":{"operationId":"export_pdf","summary":"The organization's report as a PDF, under its brand.","tags":["Exports"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","description":"The reporting window: 7, 30 or 90 days ending today (UTC). Default 30. Ignored when `from` and `to` are given.","schema":{"type":"integer","enum":[7,30,90],"default":30},"in":"query","required":false}],"x-permission":"reports.read","responses":{"200":{"description":"OK","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}}}