{
  "openapi": "3.1.0",
  "info": {
    "title": "MailSenpai DNS check API",
    "version": "1.0.0",
    "summary": "Free check of the DNS records that decide whether a domain's email gets delivered: SPF, DKIM, DMARC and MX.",
    "description": "One GET request returns whether the email DNS records of a domain are in order, what to fix and the values to publish. Free, no API key, CORS enabled. Limit: 30 checks per hour per IP address; answers served from the 15-minute cache do not count. Only public DNS records are read.",
    "contact": {
      "name": "MailSenpai",
      "url": "https://en.mailsenpai.com/dns-check-api/"
    }
  },
  "externalDocs": {
    "description": "Documentation with examples",
    "url": "https://en.mailsenpai.com/dns-check-api/"
  },
  "servers": [
    {
      "url": "https://app.mailsenpai.com/tools"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "DNS check",
      "description": "SPF, DKIM, DMARC and MX records of a domain, read from public DNS."
    }
  ],
  "paths": {
    "/dns-check": {
      "get": {
        "operationId": "checkDomainDns",
        "tags": [
          "DNS check"
        ],
        "summary": "Check the SPF, DKIM, DMARC and MX records of a domain",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 255
            },
            "example": "example.com",
            "description": "The domain to check. A URL or an email address also works: the domain is extracted."
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "it"
              ],
              "default": "en"
            },
            "description": "Language of labels, notes and tips."
          },
          {
            "name": "selector",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 63
            },
            "example": "mail",
            "description": "A DKIM selector to try first (the name before ._domainkey). Without it the most common selectors are tried."
          }
        ],
        "responses": {
          "200": {
            "description": "The report. Look at status first: a domain that does not exist or is not valid also answers 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DnsReport"
                },
                "examples": {
                  "checked": {
                    "summary": "A domain with records to fix (real response)",
                    "value": {
                      "domain": "example.com",
                      "status": "checked",
                      "lang": "en",
                      "summary": "3 things to fix",
                      "message": "In short: 3 things to fix. Below you'll find what's fine, what isn't and what to do, in order of importance.",
                      "to_fix": 3,
                      "to_check": 0,
                      "checks": {
                        "spf": {
                          "result": "fix",
                          "label": "Needs fixing",
                          "note": "There is an SPF record, but it says no server may send email on behalf of example.com. Record: v=spf1 -all."
                        },
                        "dkim": {
                          "result": "fix",
                          "label": "Needs fixing",
                          "note": "The domain publishes an empty key for any selector: this declares it signs no email at all."
                        },
                        "dmarc": {
                          "result": "ok",
                          "label": "OK",
                          "note": "It exists, with p=reject: email using your domain without permission is rejected. It doesn't ask for reports (rua), so you don't know who sends on your behalf."
                        },
                        "mx": {
                          "result": "fix",
                          "label": "Needs fixing",
                          "note": "The domain declares it receives no mail (null MX): replies and bounce notices for your emails never arrive."
                        }
                      },
                      "tips": [
                        "If you send email from example.com, replace the SPF record v=spf1 -all with one that lists the services you send from, for example v=spf1 include:your-provider-domain ~all, using the include your provider gives you.",
                        "If you send email from example.com, remove the wildcard DKIM record with the empty key and publish the key of the service you send from.",
                        "If you want to receive replies on example.com, replace the null MX record with your mail service's MX records (your mailbox provider gives them to you).",
                        "Add rua=mailto:dmarc@example.com to the DMARC record (an address that exists): you'll receive reports on who sends email on behalf of your domain."
                      ],
                      "records": {
                        "spf": [
                          "v=spf1 -all"
                        ],
                        "dmarc": [
                          "v=DMARC1;p=reject;sp=reject;adkim=s;aspf=s"
                        ],
                        "mx": [],
                        "dkim_selectors": []
                      },
                      "checked_at": "2026-10-12T11:44:15Z",
                      "cached": false,
                      "source": "MailSenpai"
                    }
                  },
                  "public_mailbox": {
                    "summary": "A public email service (real response)",
                    "value": {
                      "domain": "gmail.com",
                      "status": "public_mailbox",
                      "lang": "en",
                      "summary": "public email service",
                      "message": "gmail.com is a public email service: its records are managed by the provider. Check your own business domain instead.",
                      "to_fix": 0,
                      "to_check": 0,
                      "checks": {},
                      "tips": [],
                      "records": {},
                      "checked_at": "2026-10-12T11:44:15Z",
                      "cached": false,
                      "source": "MailSenpai"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "The domain parameter is missing or too long.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "mspck_error",
                  "message": "Add ?domain=yourcompany.com to the request.",
                  "data": {
                    "status": 422,
                    "campo": "domain"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 30 checks in an hour from the same IP address, or the service is very busy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "mspck_error",
                  "message": "Too many checks from this connection: try again in an hour.",
                  "data": {
                    "status": 429
                  }
                }
              }
            }
          },
          "500": {
            "description": "The check did not complete: try again in a minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "mspck_error",
                  "message": "The check didn't complete: try again in a minute.",
                  "data": {
                    "status": 500
                  }
                }
              }
            }
          },
          "503": {
            "description": "The check is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "mspck_error",
                  "message": "The DNS check is not available right now.",
                  "data": {
                    "status": 503
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DnsReport": {
        "type": "object",
        "required": [
          "domain",
          "status",
          "lang",
          "summary",
          "message",
          "to_fix",
          "to_check",
          "checks",
          "tips",
          "records",
          "checked_at",
          "cached",
          "source"
        ],
        "properties": {
          "domain": {
            "type": "string",
            "description": "The domain that was checked, as extracted from the request."
          },
          "status": {
            "type": "string",
            "enum": [
              "checked",
              "public_mailbox",
              "not_found",
              "invalid",
              "dns_unreachable"
            ],
            "description": "checked: records read. public_mailbox: a public email service such as gmail.com, whose records belong to the provider. not_found: the domain is not registered. invalid: not a domain name. dns_unreachable: the DNS did not answer, try again later."
          },
          "lang": {
            "type": "string",
            "enum": [
              "en",
              "it"
            ]
          },
          "summary": {
            "type": "string",
            "description": "One line, for example \"3 things to fix\"."
          },
          "message": {
            "type": "string"
          },
          "to_fix": {
            "type": "integer",
            "minimum": 0,
            "description": "How many of the four checks need fixing."
          },
          "to_check": {
            "type": "integer",
            "minimum": 0,
            "description": "How many of the four checks could not be confirmed."
          },
          "checks": {
            "type": "object",
            "description": "Empty unless status is checked.",
            "properties": {
              "spf": {
                "$ref": "#/components/schemas/Check"
              },
              "dkim": {
                "$ref": "#/components/schemas/Check"
              },
              "dmarc": {
                "$ref": "#/components/schemas/Check"
              },
              "mx": {
                "$ref": "#/components/schemas/Check"
              }
            }
          },
          "tips": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Actions in order of priority, with the values to publish."
          },
          "records": {
            "type": "object",
            "description": "The raw records found. Empty unless status is checked.",
            "properties": {
              "spf": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "dmarc": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "mx": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "priority",
                    "host"
                  ],
                  "properties": {
                    "priority": {
                      "type": "integer"
                    },
                    "host": {
                      "type": "string"
                    }
                  }
                }
              },
              "dkim_selectors": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The DKIM selectors on which a key was found."
              }
            }
          },
          "checked_at": {
            "type": "string",
            "format": "date-time"
          },
          "cached": {
            "type": "boolean",
            "description": "true when the same check ran in the last 15 minutes."
          },
          "more": {
            "type": "string",
            "format": "uri",
            "description": "The web page that runs the same check, when available for the language."
          },
          "source": {
            "type": "string",
            "const": "MailSenpai"
          }
        }
      },
      "Check": {
        "type": "object",
        "required": [
          "result",
          "label",
          "note"
        ],
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "ok",
              "fix",
              "missing",
              "check"
            ],
            "description": "ok: in order. fix: present but wrong. missing: not published. check: could not be confirmed (for DKIM: no key on the common selectors, pass selector)."
          },
          "label": {
            "type": "string",
            "description": "The result in words, in the language of the request."
          },
          "note": {
            "type": "string",
            "description": "What was found and why it matters."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "data"
        ],
        "properties": {
          "code": {
            "type": "string",
            "const": "mspck_error"
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation, in the language of the request."
          },
          "data": {
            "type": "object",
            "required": [
              "status"
            ],
            "description": "The HTTP status again, plus details that depend on the error.",
            "properties": {
              "status": {
                "type": "integer",
                "description": "Same value as the HTTP status code."
              },
              "field": {
                "type": "string",
                "description": "Name of the parameter that is missing or not valid."
              },
              "campo": {
                "type": "string",
                "description": "Name of the parameter that is missing or not valid (DNS check)."
              },
              "limit": {
                "type": "string",
                "enum": [
                  "per_ip_hour",
                  "daily_total",
                  "requests_per_ip_hour"
                ],
                "description": "Which limit was reached."
              },
              "retry_after": {
                "type": "integer",
                "description": "Seconds to wait before trying again."
              },
              "web_tool": {
                "type": "string",
                "format": "uri",
                "description": "The web page that runs the same check."
              }
            }
          }
        }
      }
    }
  }
}