{
  "openapi": "3.1.0",
  "info": {
    "title": "NoJunk Email Check",
    "version": "1.0.0",
    "description": "Email address verification for AI agents: RFC 5322 syntax check, live MX/A DNS lookup, disposable-domain detection, role-address and free-mail-provider flags, typo suggestions (gmial.com -> gmail.com), normalized form and a low/medium/high risk score. One address or up to 20 per request, same price. No mailbox probing.",
    "x-guidance": "Use GET /verify?email=john@example.com (or POST /verify with JSON {email} or {emails:[...]} for up to 20 addresses) to check an email address before you send to it, store it or trust it. Each result reports valid_syntax, has_mx with mx_hosts, disposable, role, free_provider, a typo suggestion (gmial.com -> gmail.com), normalized_email and a risk score of low/medium/high with reason codes. Costs $0.001 USDC on Base per request via x402, whether you send 1 or 20 addresses. Invalid addresses are returned as results (valid_syntax=false), not errors. No SMTP mailbox probing is done, so has_mx=true means the domain accepts mail, not that the specific mailbox exists."
  },
  "servers": [
    {
      "url": "https://nojunk-email-check.mick8511.workers.dev"
    }
  ],
  "paths": {
    "/verify": {
      "get": {
        "operationId": "verifyEmail",
        "summary": "Verify one email address or up to 20 at once: syntax, MX records, disposable, role, free provider, typo suggestion, normalized form and risk score",
        "tags": [
          "Email",
          "Validation",
          "Data Quality"
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.001000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Email address to check, e.g. 'john@example.com'. Either email or emails is required."
          },
          {
            "name": "emails",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Up to 20 addresses checked in one request for the same price (GET: comma-separated string)"
          }
        ],
        "responses": {
          "200": {
            "description": "Verification results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "email": {
                            "type": "string",
                            "description": "Address as submitted"
                          },
                          "normalized_email": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Lowercased; Gmail dots and +tags removed, googlemail.com mapped to gmail.com"
                          },
                          "valid_syntax": {
                            "type": "boolean",
                            "description": "Passes the RFC 5322 practical subset"
                          },
                          "domain": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "has_mx": {
                            "type": "boolean",
                            "description": "Domain publishes MX records"
                          },
                          "mx_hosts": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Up to 5 MX hosts by priority"
                          },
                          "disposable": {
                            "type": "boolean",
                            "description": "Domain is a known disposable/temporary mail service"
                          },
                          "role": {
                            "type": "boolean",
                            "description": "Role or functional mailbox (admin@, info@, support@, noreply@ ...)"
                          },
                          "free_provider": {
                            "type": "boolean",
                            "description": "Free consumer mailbox provider (Gmail, Yahoo, Outlook ...)"
                          },
                          "suggestion": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Likely intended address when the domain looks like a typo of a major provider"
                          },
                          "risk": {
                            "type": "string",
                            "enum": [
                              "low",
                              "medium",
                              "high"
                            ]
                          },
                          "reasons": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Machine-readable reason codes behind the risk score"
                          }
                        },
                        "required": [
                          "email",
                          "normalized_email",
                          "valid_syntax",
                          "domain",
                          "has_mx",
                          "mx_hosts",
                          "disposable",
                          "role",
                          "free_provider",
                          "suggestion",
                          "risk",
                          "reasons"
                        ]
                      }
                    },
                    "resolver": {
                      "type": "string"
                    },
                    "note": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "count",
                    "results"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed input, or more than 20 addresses (no charge)"
          },
          "402": {
            "description": "Payment Required"
          },
          "413": {
            "description": "Request too large (no charge)"
          },
          "502": {
            "description": "DNS resolver temporarily unavailable (no charge)"
          }
        }
      },
      "post": {
        "operationId": "verifyEmailPost",
        "summary": "Verify one email address or up to 20 at once: syntax, MX records, disposable, role, free provider, typo suggestion, normalized form and risk score",
        "tags": [
          "Email",
          "Validation",
          "Data Quality"
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.001000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Email address to check, e.g. 'john@example.com'. Either email or emails is required."
                  },
                  "emails": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 20,
                    "description": "Up to 20 addresses checked in one request for the same price (GET: comma-separated string)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "email": {
                            "type": "string",
                            "description": "Address as submitted"
                          },
                          "normalized_email": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Lowercased; Gmail dots and +tags removed, googlemail.com mapped to gmail.com"
                          },
                          "valid_syntax": {
                            "type": "boolean",
                            "description": "Passes the RFC 5322 practical subset"
                          },
                          "domain": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "has_mx": {
                            "type": "boolean",
                            "description": "Domain publishes MX records"
                          },
                          "mx_hosts": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Up to 5 MX hosts by priority"
                          },
                          "disposable": {
                            "type": "boolean",
                            "description": "Domain is a known disposable/temporary mail service"
                          },
                          "role": {
                            "type": "boolean",
                            "description": "Role or functional mailbox (admin@, info@, support@, noreply@ ...)"
                          },
                          "free_provider": {
                            "type": "boolean",
                            "description": "Free consumer mailbox provider (Gmail, Yahoo, Outlook ...)"
                          },
                          "suggestion": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Likely intended address when the domain looks like a typo of a major provider"
                          },
                          "risk": {
                            "type": "string",
                            "enum": [
                              "low",
                              "medium",
                              "high"
                            ]
                          },
                          "reasons": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Machine-readable reason codes behind the risk score"
                          }
                        },
                        "required": [
                          "email",
                          "normalized_email",
                          "valid_syntax",
                          "domain",
                          "has_mx",
                          "mx_hosts",
                          "disposable",
                          "role",
                          "free_provider",
                          "suggestion",
                          "risk",
                          "reasons"
                        ]
                      }
                    },
                    "resolver": {
                      "type": "string"
                    },
                    "note": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "count",
                    "results"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed input, or more than 20 addresses (no charge)"
          },
          "402": {
            "description": "Payment Required"
          },
          "413": {
            "description": "Request too large (no charge)"
          },
          "502": {
            "description": "DNS resolver temporarily unavailable (no charge)"
          }
        }
      }
    }
  }
}