{
  "openapi": "3.1.0",
  "info": {
    "title": "DomainCanary free API",
    "version": "1.0.0",
    "summary": "Check a domain's email authentication and test SPF changes, with no key.",
    "description": "The free JSON API checks a domain's DMARC, SPF and DKIM records and lists what to fix. It also compares a new SPF record with the one you publish today and lists the senders that would fail SPF under the new one. You don't need an account or a key.\n\nDomainCanary is a DMARC enforcement service that protects your domain from email spoofing without blocking your own mail. The calls run the same checks as the free tools on the site.\n\nCalls share an allowance of 30 lookups per IP address with the free tools on the site. A domain check counts as 5 lookups, or 6 when it checks a blocklist. An SPF pre-flight counts as 2. Once you've used the allowance, the API answers 429 with a Retry-After header, and the count starts again 10 minutes after your last call.\n\nAI assistants can run the same checks over MCP at https://domaincanary.com/mcp.",
    "termsOfService": "https://domaincanary.com/terms",
    "contact": {
      "name": "DomainCanary",
      "email": "contact@domaincanary.com",
      "url": "https://domaincanary.com/about"
    }
  },
  "servers": [
    {
      "url": "https://domaincanary.com"
    }
  ],
  "externalDocs": {
    "description": "API and MCP documentation",
    "url": "https://domaincanary.com/docs"
  },
  "paths": {
    "/c/{domain}": {
      "get": {
        "operationId": "checkDomain",
        "summary": "Check a domain's email authentication",
        "description": "Looks up the domain's DMARC, SPF and DKIM records, where its DMARC reports go, its MX records, the SpamCop blocklist, MTA-STS, TLS-RPT and BIMI. The answer lists every problem worst first, with the record to publish where one fixes it. It is the email health check from the site, as JSON.",
        "externalDocs": {
          "description": "Email health check",
          "url": "https://domaincanary.com/tools/checkup"
        },
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "description": "The domain to check, as in example.com.",
            "schema": {
              "type": "string",
              "maxLength": 253
            },
            "example": "example.com"
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "description": "json for this answer. txt returns the same report as plain text. Leave it out and you get the HTML page.",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "txt"
              ]
            },
            "example": "json"
          }
        ],
        "responses": {
          "200": {
            "description": "The report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckReport"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "The domain is not a valid domain name, so we did not look anything up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Your IP address has used its allowance.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before you call again.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThrottleError"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/spf-preflight": {
      "post": {
        "operationId": "spfPreflight",
        "summary": "Test a new SPF record before you publish it",
        "description": "Resolves the published SPF record and the proposed one against live DNS and compares them. The verdict is fail when the proposed record breaks SPF (more than 10 lookups, a term receivers do not read, +all) or when a sampled address that passes today would stop passing. A CI job can fail a pull request on it. Send no Authorization header. If you send one with a key that matches no account, the API answers 401.",
        "externalDocs": {
          "description": "SPF change pre-flight",
          "url": "https://domaincanary.com/tools/spf-change-check"
        },
        "requestBody": {
          "required": true,
          "description": "JSON of at most 64 KB.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "The domain, as in example.com."
                  },
                  "record": {
                    "type": "string",
                    "maxLength": 4096,
                    "description": "The SPF record you plan to publish, with at most 200 terms. Quotes copied from a DNS panel are fine."
                  }
                },
                "required": [
                  "domain",
                  "record"
                ],
                "example": {
                  "domain": "example.com",
                  "record": "v=spf1 include:_spf.google.com -all"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The comparison and its verdict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Preflight"
                }
              }
            }
          },
          "400": {
            "description": "The body is not valid JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "You sent an Authorization header with a key that matches no account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "The body is larger than 64 KB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The domain is not a domain name, or the record is missing or is not a usable SPF record. problem says what is wrong with the record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InputError"
                }
              }
            }
          },
          "429": {
            "description": "Your IP address has used its allowance.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before you call again.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The DNS lookup for the domain did not complete. Try again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in one sentence."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "ThrottleError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "retry_after": {
            "type": "integer",
            "minimum": 1,
            "description": "Seconds until you can call again."
          }
        },
        "required": [
          "error",
          "retry_after"
        ],
        "additionalProperties": false
      },
      "InputError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "problem": {
            "type": "string",
            "enum": [
              "empty",
              "too-long",
              "control-chars",
              "not-spf",
              "too-many-terms",
              "term-too-long"
            ],
            "description": "Why the record was not read."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "CheckReport": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "description": "The domain checked, in lowercase."
          },
          "url": {
            "type": "string",
            "description": "The address of the same report as a web page."
          },
          "complete": {
            "type": "boolean",
            "description": "False when a lookup did not complete. An empty issues list then proves nothing."
          },
          "issues": {
            "type": "array",
            "description": "Every error and warning, worst first.",
            "items": {
              "type": "object",
              "properties": {
                "check": {
                  "type": "string",
                  "enum": [
                    "dmarc",
                    "spf",
                    "dkim",
                    "reports",
                    "mx",
                    "blocklists",
                    "mta-sts",
                    "tls-rpt",
                    "bimi"
                  ]
                },
                "level": {
                  "type": "string",
                  "enum": [
                    "error",
                    "warn"
                  ]
                },
                "message": {
                  "type": "string"
                },
                "fix": {
                  "type": "object",
                  "description": "A record that fixes the issue, ready to publish.",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "The DNS name to publish at."
                    },
                    "type": {
                      "type": "string",
                      "const": "TXT"
                    },
                    "value": {
                      "type": "string",
                      "description": "The exact record value."
                    },
                    "note": {
                      "type": "string",
                      "description": "What to do before you publish it."
                    }
                  },
                  "required": [
                    "name",
                    "type",
                    "value"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "check",
                "level",
                "message"
              ],
              "additionalProperties": false
            }
          },
          "checks": {
            "type": "object",
            "description": "One entry per check. A domain whose null MX says it takes no mail has no mta-sts or tls-rpt entry.",
            "properties": {
              "dmarc": {
                "$ref": "#/components/schemas/CheckRow"
              },
              "spf": {
                "$ref": "#/components/schemas/CheckRow"
              },
              "dkim": {
                "$ref": "#/components/schemas/CheckRow"
              },
              "reports": {
                "$ref": "#/components/schemas/CheckRow"
              },
              "mx": {
                "$ref": "#/components/schemas/CheckRow"
              },
              "blocklists": {
                "$ref": "#/components/schemas/CheckRow"
              },
              "mta-sts": {
                "$ref": "#/components/schemas/CheckRow"
              },
              "tls-rpt": {
                "$ref": "#/components/schemas/CheckRow"
              },
              "bimi": {
                "$ref": "#/components/schemas/CheckRow"
              }
            },
            "required": [
              "dmarc",
              "spf",
              "dkim",
              "reports",
              "mx",
              "blocklists",
              "bimi"
            ],
            "additionalProperties": false
          },
          "blocklists_checked": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "domain",
          "url",
          "complete",
          "issues",
          "checks",
          "blocklists_checked"
        ],
        "additionalProperties": false
      },
      "CheckRow": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "warn",
              "error",
              "unknown"
            ]
          },
          "summary": {
            "type": "string",
            "description": "One clause on how the check came out."
          },
          "detail": {
            "type": "string",
            "description": "The record or value the check read, when there is one."
          }
        },
        "required": [
          "status",
          "summary"
        ],
        "additionalProperties": false
      },
      "Preflight": {
        "type": "object",
        "properties": {
          "checked_at": {
            "type": "string",
            "format": "date-time"
          },
          "domain": {
            "type": "string"
          },
          "verdict": {
            "type": "string",
            "enum": [
              "fail",
              "warn",
              "pass",
              "unchanged"
            ],
            "description": "fail: publishing breaks SPF or drops a sender. warn: some senders could not be checked. pass: no tested address loses its pass. unchanged: the same senders as today."
          },
          "lookups": {
            "type": "object",
            "properties": {
              "published": {
                "type": "integer",
                "minimum": 0
              },
              "proposed": {
                "type": "integer",
                "minimum": 0
              },
              "limit": {
                "type": "integer",
                "minimum": 0,
                "description": "Receivers stop at this many DNS lookups and return permerror."
              }
            },
            "required": [
              "published",
              "proposed",
              "limit"
            ],
            "additionalProperties": false
          },
          "all": {
            "type": "object",
            "description": "The all term each record ends in, or null when it has none.",
            "properties": {
              "published": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "proposed": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "published",
              "proposed"
            ],
            "additionalProperties": false
          },
          "removed": {
            "type": "array",
            "description": "Terms whose ranges the proposed record no longer covers.",
            "items": {
              "type": "object",
              "properties": {
                "term": {
                  "type": "string",
                  "description": "The SPF term, exactly as it appears in the record."
                },
                "ranges": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "The address ranges under it."
                },
                "ipv4_addresses": {
                  "type": "integer",
                  "minimum": 0
                },
                "ipv6_ranges": {
                  "type": "integer",
                  "minimum": 0
                },
                "traffic": {
                  "oneOf": [
                    {
                      "type": "null"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "messages": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "senders": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "last_seen": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        }
                      },
                      "required": [
                        "messages",
                        "senders",
                        "last_seen"
                      ],
                      "additionalProperties": false
                    }
                  ],
                  "description": "Mail from these ranges in the account's DMARC reports. Null without a key."
                }
              },
              "required": [
                "term",
                "ranges",
                "ipv4_addresses",
                "ipv6_ranges",
                "traffic"
              ],
              "additionalProperties": false
            }
          },
          "added": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "term": {
                  "type": "string",
                  "description": "The SPF term, exactly as it appears in the record."
                },
                "ranges": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "The address ranges under it."
                },
                "ipv4_addresses": {
                  "type": "integer",
                  "minimum": 0
                },
                "ipv6_ranges": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "required": [
                "term",
                "ranges",
                "ipv4_addresses",
                "ipv6_ranges"
              ],
              "additionalProperties": false
            }
          },
          "lost": {
            "type": "object",
            "properties": {
              "ipv4_addresses": {
                "type": "integer",
                "minimum": 0
              },
              "ipv6_ranges": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "ipv4_addresses",
              "ipv6_ranges"
            ],
            "additionalProperties": false
          },
          "floor": {
            "type": "object",
            "properties": {
              "applies": {
                "type": "boolean",
                "description": "True when the address counts are lower bounds."
              },
              "terms": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "a",
                    "mx",
                    "exists",
                    "ptr",
                    "macro"
                  ]
                }
              }
            },
            "required": [
              "applies",
              "terms"
            ],
            "additionalProperties": false
          },
          "traffic": {
            "description": "Whether the removed ranges were compared with DMARC report traffic. Without a key, checked is false and reason is no-key.",
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "checked": {
                    "type": "boolean",
                    "const": false
                  },
                  "reason": {
                    "type": "string",
                    "enum": [
                      "no-key",
                      "not-in-account",
                      "not-verified",
                      "no-reports",
                      "stale-reports"
                    ]
                  }
                },
                "required": [
                  "checked",
                  "reason"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "checked": {
                    "type": "boolean",
                    "const": true
                  },
                  "window_days": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Up to 90."
                  },
                  "covered_days": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "senders_truncated": {
                    "type": "boolean"
                  },
                  "messages": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "senders": {
                    "type": "integer",
                    "minimum": 0
                  }
                },
                "required": [
                  "checked",
                  "window_days",
                  "covered_days",
                  "senders_truncated",
                  "messages",
                  "senders"
                ],
                "additionalProperties": false
              }
            ]
          },
          "findings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "level": {
                  "type": "string",
                  "enum": [
                    "error",
                    "warning",
                    "notice"
                  ]
                },
                "text": {
                  "type": "string"
                }
              },
              "required": [
                "level",
                "text"
              ],
              "additionalProperties": false
            }
          },
          "url": {
            "type": "string",
            "description": "The SPF change pre-flight page on the site."
          }
        },
        "required": [
          "checked_at",
          "domain",
          "verdict",
          "lookups",
          "all",
          "removed",
          "added",
          "lost",
          "floor",
          "traffic",
          "findings",
          "url"
        ],
        "additionalProperties": false
      }
    }
  }
}