{
  "openapi": "3.0.3",
  "info": {
    "title": "Email Validator",
    "description": "Validate email addresses: syntax, MX/deliverability, disposable & role detection, and typo suggestions.",
    "version": "1.0.0"
  },
  "components": {
    "schemas": {}
  },
  "paths": {
    "/validate": {
      "get": {
        "summary": "Validate an email address (GET)",
        "tags": [
          "Email"
        ],
        "description": "Checks syntax, MX/deliverability, disposable & role-account detection, and suggests typo fixes.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "example": "jane.doe@gmail.com",
            "in": "query",
            "name": "email",
            "required": true,
            "description": "Email address to validate"
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "normalized": {
                      "type": "string"
                    },
                    "valid": {
                      "type": "boolean"
                    },
                    "syntaxValid": {
                      "type": "boolean"
                    },
                    "local": {
                      "type": "string",
                      "nullable": true
                    },
                    "domain": {
                      "type": "string",
                      "nullable": true
                    },
                    "hasMx": {
                      "type": "boolean"
                    },
                    "mxRecords": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "exchange": {
                            "type": "string"
                          },
                          "priority": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "isDisposable": {
                      "type": "boolean"
                    },
                    "isRoleAccount": {
                      "type": "boolean"
                    },
                    "didYouMean": {
                      "type": "string",
                      "nullable": true
                    },
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Bad request",
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Validate an email address (POST)",
        "tags": [
          "Email"
        ],
        "description": "Checks syntax, MX/deliverability, disposable & role-account detection, and suggests typo fixes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "normalized": {
                      "type": "string"
                    },
                    "valid": {
                      "type": "boolean"
                    },
                    "syntaxValid": {
                      "type": "boolean"
                    },
                    "local": {
                      "type": "string",
                      "nullable": true
                    },
                    "domain": {
                      "type": "string",
                      "nullable": true
                    },
                    "hasMx": {
                      "type": "boolean"
                    },
                    "mxRecords": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "exchange": {
                            "type": "string"
                          },
                          "priority": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "isDisposable": {
                      "type": "boolean"
                    },
                    "isRoleAccount": {
                      "type": "boolean"
                    },
                    "didYouMean": {
                      "type": "string",
                      "nullable": true
                    },
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Bad request",
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/validate-batch": {
      "post": {
        "summary": "Validate up to 100 emails at once",
        "tags": [
          "Email"
        ],
        "description": "Runs the full validation on each email in the array (max 100).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "emails"
                ],
                "properties": {
                  "emails": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 100
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "number"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "email": {
                            "type": "string"
                          },
                          "normalized": {
                            "type": "string"
                          },
                          "valid": {
                            "type": "boolean"
                          },
                          "syntaxValid": {
                            "type": "boolean"
                          },
                          "local": {
                            "type": "string",
                            "nullable": true
                          },
                          "domain": {
                            "type": "string",
                            "nullable": true
                          },
                          "hasMx": {
                            "type": "boolean"
                          },
                          "mxRecords": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "exchange": {
                                  "type": "string"
                                },
                                "priority": {
                                  "type": "number"
                                }
                              }
                            }
                          },
                          "isDisposable": {
                            "type": "boolean"
                          },
                          "isRoleAccount": {
                            "type": "boolean"
                          },
                          "didYouMean": {
                            "type": "string",
                            "nullable": true
                          },
                          "reason": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Bad request",
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://web-toolbox-api-production.up.railway.app/email",
      "description": "Production"
    }
  ]
}