{
  "openapi": "3.0.3",
  "info": {
    "title": "MailGrade",
    "version": "1.0.0",
    "description": "Deterministic email and domain deliverability intelligence, derived entirely from DNS. No SMTP probing, so nothing we do can get an IP blocklisted. No addresses are stored, so integrating adds no data-protection obligations. Every response carries the evidence that produced it.",
    "contact": {
      "url": "https://www.mailgrade.dev"
    }
  },
  "servers": [
    {
      "url": "https://www.mailgrade.dev"
    }
  ],
  "tags": [
    {
      "name": "Verification",
      "description": "Score individual addresses"
    },
    {
      "name": "Domains",
      "description": "Audit a domain's mail configuration"
    },
    {
      "name": "Meta",
      "description": "Service and dataset metadata"
    }
  ],
  "paths": {
    "/v1/verify": {
      "get": {
        "tags": [
          "Verification"
        ],
        "operationId": "verifyEmail",
        "summary": "Verify a single email address",
        "description": "Scores one address 0-100 and returns a verdict with the full evidence. Detects disposable domains, role accounts, missing or null MX records, unresolvable mail exchangers, and likely typos with a suggested correction.",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "required": true,
            "description": "The address to verify. A display name and angle brackets are accepted.",
            "schema": {
              "type": "string"
            },
            "example": "jane@gmial.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Verification"
        ],
        "operationId": "verifyEmailPost",
        "summary": "Verify a single email address (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "jane@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/verify/batch": {
      "post": {
        "tags": [
          "Verification"
        ],
        "operationId": "verifyBatch",
        "summary": "Verify up to 100 addresses in one call",
        "description": "Use for list hygiene before a send. Returns per-address results plus a summary count by verdict.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "emails"
                ],
                "properties": {
                  "emails": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "jane@example.com",
                      "support@acme.io",
                      "x@mailinator.com"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch verification results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "deliverable": {
                          "type": "integer"
                        },
                        "risky": {
                          "type": "integer"
                        },
                        "undeliverable": {
                          "type": "integer"
                        },
                        "unknown": {
                          "type": "integer"
                        }
                      }
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/VerifyResult"
                      }
                    },
                    "took_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/domain": {
      "get": {
        "tags": [
          "Domains"
        ],
        "operationId": "auditDomain",
        "summary": "Audit a domain's deliverability and anti-spoofing posture",
        "description": "Checks MX, SPF (including the 10-lookup limit that silently breaks authentication), DMARC policy and coverage, DKIM selector discovery, MTA-STS, TLS-RPT, BIMI and DNSSEC. Returns a grade and a specific fix for every problem found.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Domain report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainReport"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/datasets": {
      "get": {
        "tags": [
          "Meta"
        ],
        "operationId": "datasets",
        "summary": "Dataset freshness",
        "description": "Size and last-updated timestamp of the disposable-domain list in use.",
        "responses": {
          "200": {
            "description": "Dataset metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "disposable_domains": {
                      "type": "object",
                      "properties": {
                        "size": {
                          "type": "integer"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "kv",
                            "seed"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Reason": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "likely_typo"
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "warning",
              "fatal"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "VerifyResult": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "example": "jane@gmial.com"
          },
          "normalized": {
            "type": "string"
          },
          "local_part": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "canonical": {
            "type": "string",
            "description": "Two addresses sharing a canonical form reach the same mailbox."
          },
          "verdict": {
            "type": "string",
            "enum": [
              "deliverable",
              "risky",
              "undeliverable",
              "unknown"
            ],
            "description": "deliverable = safe to send. risky = deliverable but flagged. undeliverable = do not send. unknown = DNS was unreachable, retry."
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "example": 10
          },
          "checks": {
            "type": "object",
            "properties": {
              "syntax": {
                "type": "boolean"
              },
              "domain_exists": {
                "type": "boolean"
              },
              "has_mx": {
                "type": "boolean"
              },
              "mx_resolves": {
                "type": "boolean"
              },
              "accepts_mail": {
                "type": "boolean"
              },
              "disposable": {
                "type": "boolean"
              },
              "role_account": {
                "type": "boolean"
              },
              "free_provider": {
                "type": "boolean"
              },
              "typo_suspected": {
                "type": "boolean"
              }
            }
          },
          "suggestion": {
            "type": "string",
            "nullable": true,
            "example": "jane@gmail.com",
            "description": "The corrected address when a provider typo is detected."
          },
          "mx": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "priority": {
                  "type": "integer"
                },
                "host": {
                  "type": "string"
                }
              }
            }
          },
          "provider": {
            "type": "object",
            "nullable": true,
            "properties": {
              "name": {
                "type": "string"
              },
              "kind": {
                "type": "string"
              }
            }
          },
          "reasons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Reason"
            }
          },
          "took_ms": {
            "type": "integer"
          }
        }
      },
      "Finding": {
        "type": "object",
        "properties": {
          "check": {
            "type": "string",
            "example": "dmarc"
          },
          "status": {
            "type": "string",
            "enum": [
              "pass",
              "warn",
              "fail"
            ]
          },
          "observed": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string"
          },
          "fix": {
            "type": "string",
            "description": "Present whenever status is not pass."
          }
        }
      },
      "DomainReport": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "example": "example.com"
          },
          "grade": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D",
              "F"
            ]
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "can_receive_mail": {
            "type": "boolean"
          },
          "spoofable": {
            "type": "boolean",
            "description": "True when DMARC is absent or set to p=none."
          },
          "provider": {
            "type": "object",
            "nullable": true,
            "properties": {
              "name": {
                "type": "string"
              },
              "kind": {
                "type": "string"
              }
            }
          },
          "mx": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "priority": {
                  "type": "integer"
                },
                "host": {
                  "type": "string"
                }
              }
            }
          },
          "spf": {
            "type": "object",
            "properties": {
              "present": {
                "type": "boolean"
              },
              "record": {
                "type": "string",
                "nullable": true
              },
              "policy": {
                "type": "string",
                "nullable": true,
                "example": "-all"
              },
              "lookups": {
                "type": "integer",
                "description": "DNS-querying mechanisms. Above 10 causes a permerror."
              }
            }
          },
          "dmarc": {
            "type": "object",
            "properties": {
              "present": {
                "type": "boolean"
              },
              "record": {
                "type": "string",
                "nullable": true
              },
              "policy": {
                "type": "string",
                "nullable": true,
                "example": "reject"
              },
              "pct": {
                "type": "integer",
                "nullable": true
              },
              "rua": {
                "type": "boolean"
              }
            }
          },
          "dkim": {
            "type": "object",
            "properties": {
              "present": {
                "type": "boolean"
              },
              "selectors": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "discovery": {
                "type": "string",
                "enum": [
                  "ok",
                  "wildcard_zone"
                ]
              }
            }
          },
          "bimi": {
            "type": "boolean"
          },
          "mta_sts": {
            "type": "boolean"
          },
          "tls_rpt": {
            "type": "boolean"
          },
          "dnssec": {
            "type": "boolean"
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Finding"
            }
          },
          "took_ms": {
            "type": "integer"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}