{"openapi":"3.1.0","info":{"title":"MailCheck API","version":"1.0.0","description":"Email address and domain checks for AI agents: syntax, MX, disposable/role/free flags, typo suggestions, SPF/DMARC/DKIM, RDAP and a deliverability grade. Pay per item with x402 (USDC on Base) or Lightning sats. No signup.\n\nClient note: Send a descriptive User-Agent header (e.g. User-Agent: mailcheck-client/1.0). Cloudflare blocks Python urllib's default User-Agent (\"Python-urllib/3.x\") on workers.dev with HTTP 403 \"error code: 1010\" before the request reaches this API. curl, python-requests and fetch work as-is. No API key is needed.","license":{"name":"Proprietary (pay-per-use API)","url":"https://mailcheck.toolschemaforge.workers.dev/"},"x-guidance":"Use /v1/free/email-check or /v1/free/domain-check for up to 50 free checks per day. Paid: x402 (USDC on Base, $0.001 per item) on /v1/email-check and /v1/domain-check, or Lightning prepaid credits via POST /v1/credits."},"servers":[{"url":"https://mailcheck.toolschemaforge.workers.dev"}],"tags":[{"name":"paid","description":"x402 pay-per-item routes"},{"name":"free","description":"Free tier, 50 checks/day per IP"},{"name":"lightning","description":"Lightning prepaid credits"},{"name":"meta","description":"Docs and discovery"}],"paths":{"/v1/email-check":{"post":{"operationId":"emailCheck","summary":"Validate email addresses: syntax, normalization, MX via DNS-over-HTTPS, disposable/role/free-provider flags, typo suggestion, verdict and score","description":"Check 1-100 email addresses ($0.001 each): RFC syntax, normalization and canonical form, MX lookup (A fallback), disposable domain (CC0 list), role account, free provider, typo suggestion (gmial.com -> gmail.com), verdict and 0-100 score. No SMTP probing.","tags":["paid"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"One email address"},"emails":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Batch of up to 100 addresses (priced per address)"}}},"example":{"emails":["jane.doe@gmial.com","info@example.com"]}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"email":{"type":["string","null"],"description":"Normalized address (lowercased, IDN domain in punycode)"},"syntax_valid":{"type":"boolean"},"reason":{"type":"string","description":"Syntax failure code when syntax_valid is false"},"local":{"type":["string","null"]},"domain":{"type":["string","null"]},"canonical":{"type":["string","null"],"description":"Provider-aware canonical form (+tags removed, Gmail dots removed)"},"mx":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["ok","a_fallback","null_mx","none","nxdomain","error","skipped"]},"source":{"type":"string","enum":["dns","known_provider"]},"records":{"type":"array","items":{"type":"object","properties":{"priority":{"type":"integer"},"exchange":{"type":"string"}}}},"a_records":{"type":"array","items":{"type":"string"}}}},"flags":{"type":"object","properties":{"disposable":{"type":"boolean"},"role_account":{"type":"boolean"},"free_provider":{"type":"boolean"},"plus_tag":{"type":"boolean"}}},"suggestion":{"type":["string","null"],"description":"Likely intended domain for a typo, e.g. gmail.com for gmial.com"},"verdict":{"type":"string","enum":["valid","risky","invalid","disposable","unknown"]},"score":{"type":"integer","minimum":0,"maximum":100},"reasons":{"type":"array","items":{"type":"string"}}},"required":["input","syntax_valid","flags","verdict","score","reasons"]}},"summary":{"type":"object"}}},"example":{"count":1,"results":[{"input":"jane.doe@gmial.com","email":"jane.doe@gmial.com","syntax_valid":true,"local":"jane.doe","domain":"gmial.com","canonical":"jane.doe@gmial.com","mx":{"status":"ok","source":"dns","records":[{"priority":10,"exchange":"mx.example-parking.net"}]},"flags":{"disposable":false,"role_account":false,"free_provider":false,"plus_tag":false},"suggestion":"gmail.com","verdict":"risky","score":60,"reasons":["possible typo: did you mean gmail.com?"]}],"summary":{"valid":0,"risky":1,"invalid":0,"disposable":0,"unknown":0}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Payment required: $0.001 USDC per item via x402 (PAYMENT-REQUIRED header), or 1 sat per item with Lightning credits (X-Credits-Token)"}},"security":[{"x402":[]},{"creditsToken":[]}],"x-payment-info":{"protocols":["x402"],"price":{"mode":"dynamic","currency":"USD","per_item":"0.001"},"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x7a3C00Ef0969378A3E74455cde3Dc87C0f016dfa"}},"get":{"operationId":"emailCheckGet","summary":"Validate email addresses: syntax, normalization, MX via DNS-over-HTTPS, disposable/role/free-provider flags, typo suggestion, verdict and score (GET form)","tags":["paid"],"parameters":[{"name":"email","in":"query","schema":{"type":"string"}},{"name":"emails","in":"query","schema":{"type":"string"},"description":"Comma-separated list"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"email":{"type":["string","null"],"description":"Normalized address (lowercased, IDN domain in punycode)"},"syntax_valid":{"type":"boolean"},"reason":{"type":"string","description":"Syntax failure code when syntax_valid is false"},"local":{"type":["string","null"]},"domain":{"type":["string","null"]},"canonical":{"type":["string","null"],"description":"Provider-aware canonical form (+tags removed, Gmail dots removed)"},"mx":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["ok","a_fallback","null_mx","none","nxdomain","error","skipped"]},"source":{"type":"string","enum":["dns","known_provider"]},"records":{"type":"array","items":{"type":"object","properties":{"priority":{"type":"integer"},"exchange":{"type":"string"}}}},"a_records":{"type":"array","items":{"type":"string"}}}},"flags":{"type":"object","properties":{"disposable":{"type":"boolean"},"role_account":{"type":"boolean"},"free_provider":{"type":"boolean"},"plus_tag":{"type":"boolean"}}},"suggestion":{"type":["string","null"],"description":"Likely intended domain for a typo, e.g. gmail.com for gmial.com"},"verdict":{"type":"string","enum":["valid","risky","invalid","disposable","unknown"]},"score":{"type":"integer","minimum":0,"maximum":100},"reasons":{"type":"array","items":{"type":"string"}}},"required":["input","syntax_valid","flags","verdict","score","reasons"]}},"summary":{"type":"object"}}},"example":{"count":1,"results":[{"input":"jane.doe@gmial.com","email":"jane.doe@gmial.com","syntax_valid":true,"local":"jane.doe","domain":"gmial.com","canonical":"jane.doe@gmial.com","mx":{"status":"ok","source":"dns","records":[{"priority":10,"exchange":"mx.example-parking.net"}]},"flags":{"disposable":false,"role_account":false,"free_provider":false,"plus_tag":false},"suggestion":"gmail.com","verdict":"risky","score":60,"reasons":["possible typo: did you mean gmail.com?"]}],"summary":{"valid":0,"risky":1,"invalid":0,"disposable":0,"unknown":0}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Payment required: $0.001 USDC per item via x402 (PAYMENT-REQUIRED header), or 1 sat per item with Lightning credits (X-Credits-Token)"}},"security":[{"x402":[]},{"creditsToken":[]}],"x-payment-info":{"protocols":["x402"],"price":{"mode":"dynamic","currency":"USD","per_item":"0.001"},"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x7a3C00Ef0969378A3E74455cde3Dc87C0f016dfa"}}},"/v1/free/email-check":{"post":{"operationId":"emailCheckFree","summary":"FREE tier: Validate email addresses: syntax, normalization, MX via DNS-over-HTTPS, disposable/role/free-provider flags, typo suggestion, verdict and score","description":"Same output as /v1/email-check. 50 free checks per day per IP (each item counts), up to 10 item(s) per call. When the quota is used up it returns HTTP 402 with x402 payment requirements for the paid route.","tags":["free"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"One email address"},"emails":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Batch of up to 100 addresses (priced per address)"}}},"example":{"emails":["jane.doe@gmial.com","info@example.com"]}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"email":{"type":["string","null"],"description":"Normalized address (lowercased, IDN domain in punycode)"},"syntax_valid":{"type":"boolean"},"reason":{"type":"string","description":"Syntax failure code when syntax_valid is false"},"local":{"type":["string","null"]},"domain":{"type":["string","null"]},"canonical":{"type":["string","null"],"description":"Provider-aware canonical form (+tags removed, Gmail dots removed)"},"mx":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["ok","a_fallback","null_mx","none","nxdomain","error","skipped"]},"source":{"type":"string","enum":["dns","known_provider"]},"records":{"type":"array","items":{"type":"object","properties":{"priority":{"type":"integer"},"exchange":{"type":"string"}}}},"a_records":{"type":"array","items":{"type":"string"}}}},"flags":{"type":"object","properties":{"disposable":{"type":"boolean"},"role_account":{"type":"boolean"},"free_provider":{"type":"boolean"},"plus_tag":{"type":"boolean"}}},"suggestion":{"type":["string","null"],"description":"Likely intended domain for a typo, e.g. gmail.com for gmial.com"},"verdict":{"type":"string","enum":["valid","risky","invalid","disposable","unknown"]},"score":{"type":"integer","minimum":0,"maximum":100},"reasons":{"type":"array","items":{"type":"string"}}},"required":["input","syntax_valid","flags","verdict","score","reasons"]}},"summary":{"type":"object"}}},"example":{"count":1,"results":[{"input":"jane.doe@gmial.com","email":"jane.doe@gmial.com","syntax_valid":true,"local":"jane.doe","domain":"gmial.com","canonical":"jane.doe@gmial.com","mx":{"status":"ok","source":"dns","records":[{"priority":10,"exchange":"mx.example-parking.net"}]},"flags":{"disposable":false,"role_account":false,"free_provider":false,"plus_tag":false},"suggestion":"gmail.com","verdict":"risky","score":60,"reasons":["possible typo: did you mean gmail.com?"]}],"summary":{"valid":0,"risky":1,"invalid":0,"disposable":0,"unknown":0}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Free quota used up; pay per item"}}}},"/v1/domain-check":{"post":{"operationId":"domainCheck","summary":"Domain intel: A/AAAA/MX/NS/TXT via DoH, SPF and DMARC parsing, DKIM selector probe, RDAP registration data and a deliverability/security grade","description":"Check 1-2 domains ($0.001 each): A/AAAA/MX/NS/TXT records, SPF parse (all qualifier, includes, lookup count), DMARC parse (policy, pct, rua), DKIM keys at common selectors, RDAP registrar/created/expiry/status, and an A-F grade with reasons.","tags":["paid"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Domain, email address or URL"},"domains":{"type":"array","items":{"type":"string"},"maxItems":2,"description":"Up to 2 domains (priced per domain)"}}},"example":{"domain":"example.org"}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"domain":{"type":["string","null"]},"valid":{"type":"boolean"},"exists":{"type":"boolean"},"dns":{"type":["object","null"],"description":"a, aaaa, mx, ns, txt records and per-type lookup status"},"mail":{"type":["object","null"],"description":"accepts_mail, null_mx, spf (parsed), dmarc (parsed), dkim (selectors found)"},"registration":{"type":["object","null"],"description":"RDAP: registrar, created, expires, updated, statuses, nameservers, dnssec, age_days, days_to_expiry"},"grade":{"type":"string","enum":["A","B","C","D","F"]},"score":{"type":"integer"},"reasons":{"type":"array","items":{"type":"string"}}},"required":["input","valid","grade","score","reasons"]}}}},"example":{"count":1,"results":[{"input":"example.org","domain":"example.org","valid":true,"exists":true,"mail":{"accepts_mail":false,"null_mx":true,"spf":{"present":true,"all":"-all"},"dmarc":{"present":true,"policy":"reject"},"dkim":{"found":[]}},"registration":{"status":"ok","registrar":"Example Registrar","created":"1995-08-31T04:00:00Z","expires":"2027-08-30T04:00:00Z"},"grade":"A","score":100,"reasons":["null MX: domain declares it sends/receives no mail"]}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Payment required: $0.001 USDC per item via x402 (PAYMENT-REQUIRED header), or 1 sat per item with Lightning credits (X-Credits-Token)"}},"security":[{"x402":[]},{"creditsToken":[]}],"x-payment-info":{"protocols":["x402"],"price":{"mode":"dynamic","currency":"USD","per_item":"0.001"},"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x7a3C00Ef0969378A3E74455cde3Dc87C0f016dfa"}},"get":{"operationId":"domainCheckGet","summary":"Domain intel: A/AAAA/MX/NS/TXT via DoH, SPF and DMARC parsing, DKIM selector probe, RDAP registration data and a deliverability/security grade (GET form)","tags":["paid"],"parameters":[{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"domains","in":"query","schema":{"type":"string"},"description":"Comma-separated list"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"domain":{"type":["string","null"]},"valid":{"type":"boolean"},"exists":{"type":"boolean"},"dns":{"type":["object","null"],"description":"a, aaaa, mx, ns, txt records and per-type lookup status"},"mail":{"type":["object","null"],"description":"accepts_mail, null_mx, spf (parsed), dmarc (parsed), dkim (selectors found)"},"registration":{"type":["object","null"],"description":"RDAP: registrar, created, expires, updated, statuses, nameservers, dnssec, age_days, days_to_expiry"},"grade":{"type":"string","enum":["A","B","C","D","F"]},"score":{"type":"integer"},"reasons":{"type":"array","items":{"type":"string"}}},"required":["input","valid","grade","score","reasons"]}}}},"example":{"count":1,"results":[{"input":"example.org","domain":"example.org","valid":true,"exists":true,"mail":{"accepts_mail":false,"null_mx":true,"spf":{"present":true,"all":"-all"},"dmarc":{"present":true,"policy":"reject"},"dkim":{"found":[]}},"registration":{"status":"ok","registrar":"Example Registrar","created":"1995-08-31T04:00:00Z","expires":"2027-08-30T04:00:00Z"},"grade":"A","score":100,"reasons":["null MX: domain declares it sends/receives no mail"]}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Payment required: $0.001 USDC per item via x402 (PAYMENT-REQUIRED header), or 1 sat per item with Lightning credits (X-Credits-Token)"}},"security":[{"x402":[]},{"creditsToken":[]}],"x-payment-info":{"protocols":["x402"],"price":{"mode":"dynamic","currency":"USD","per_item":"0.001"},"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x7a3C00Ef0969378A3E74455cde3Dc87C0f016dfa"}}},"/v1/free/domain-check":{"post":{"operationId":"domainCheckFree","summary":"FREE tier: Domain intel: A/AAAA/MX/NS/TXT via DoH, SPF and DMARC parsing, DKIM selector probe, RDAP registration data and a deliverability/security grade","description":"Same output as /v1/domain-check. 50 free checks per day per IP (each item counts), up to 1 item(s) per call. When the quota is used up it returns HTTP 402 with x402 payment requirements for the paid route.","tags":["free"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Domain, email address or URL"},"domains":{"type":"array","items":{"type":"string"},"maxItems":2,"description":"Up to 2 domains (priced per domain)"}}},"example":{"domain":"example.org"}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"domain":{"type":["string","null"]},"valid":{"type":"boolean"},"exists":{"type":"boolean"},"dns":{"type":["object","null"],"description":"a, aaaa, mx, ns, txt records and per-type lookup status"},"mail":{"type":["object","null"],"description":"accepts_mail, null_mx, spf (parsed), dmarc (parsed), dkim (selectors found)"},"registration":{"type":["object","null"],"description":"RDAP: registrar, created, expires, updated, statuses, nameservers, dnssec, age_days, days_to_expiry"},"grade":{"type":"string","enum":["A","B","C","D","F"]},"score":{"type":"integer"},"reasons":{"type":"array","items":{"type":"string"}}},"required":["input","valid","grade","score","reasons"]}}}},"example":{"count":1,"results":[{"input":"example.org","domain":"example.org","valid":true,"exists":true,"mail":{"accepts_mail":false,"null_mx":true,"spf":{"present":true,"all":"-all"},"dmarc":{"present":true,"policy":"reject"},"dkim":{"found":[]}},"registration":{"status":"ok","registrar":"Example Registrar","created":"1995-08-31T04:00:00Z","expires":"2027-08-30T04:00:00Z"},"grade":"A","score":100,"reasons":["null MX: domain declares it sends/receives no mail"]}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Free quota used up; pay per item"}}}},"/v1/credits":{"post":{"operationId":"buyCredits","summary":"Buy Lightning prepaid credits (1 sat = 1 check, 10-50000 sats)","tags":["lightning"],"security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sats":{"type":"integer","minimum":10,"maximum":50000}}},"example":{"sats":100}}}},"responses":{"200":{"description":"{payment_id, bolt11, sats, poll}"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/v1/credits/{payment_id}":{"get":{"operationId":"pollCredits","summary":"Poll a credits invoice; returns {status:'paid', token} once paid","tags":["lightning"],"security":[],"parameters":[{"name":"payment_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"pending or paid + token"},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/v1/credits/balance":{"get":{"operationId":"creditsBalance","summary":"Remaining credits for X-Credits-Token","tags":["lightning"],"security":[],"parameters":[{"name":"X-Credits-Token","in":"header","required":true,"schema":{"type":"string"},"description":"Credits token from a paid invoice"}],"responses":{"200":{"description":"{valid, balance}"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/":{"get":{"operationId":"landing","summary":"Human-readable docs page with curl examples","tags":["meta"],"security":[],"responses":{"200":{"description":"Human-readable docs page with curl examples","content":{"text/html":{}}}}}},"/openapi.json":{"get":{"operationId":"openapi","summary":"This OpenAPI document","tags":["meta"],"security":[],"responses":{"200":{"description":"This OpenAPI document","content":{"application/json":{}}}}}},"/health":{"get":{"operationId":"health","summary":"Health check","tags":["meta"],"security":[],"responses":{"200":{"description":"Health check","content":{"application/json":{}}}}}},"/llms.txt":{"get":{"operationId":"llmsTxt","summary":"Plain-text summary for LLM agents","tags":["meta"],"security":[],"responses":{"200":{"description":"Plain-text summary for LLM agents","content":{"text/plain":{}}}}}},"/.well-known/x402":{"get":{"operationId":"x402Manifest","summary":"x402 resource list","tags":["meta"],"security":[],"responses":{"200":{"description":"x402 resource list","content":{"application/json":{}}}}}},"/.well-known/glama.json":{"get":{"operationId":"glamaClaim","summary":"Glama connector ownership claim","tags":["meta"],"security":[],"responses":{"200":{"description":"Glama connector ownership claim","content":{"application/json":{}}}}}},"/.well-known/402index-verify.txt":{"get":{"operationId":"index402Verify","summary":"402index domain-verification hash (404 if not configured)","tags":["meta"],"security":[],"responses":{"200":{"description":"402index domain-verification hash (404 if not configured)","content":{"text/plain":{}}},"404":{"description":"Not configured"}}}}},"components":{"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 v2 payment payload (exact scheme, USDC on Base eip155:8453). Call without it to get the 402 PAYMENT-REQUIRED challenge."},"creditsToken":{"type":"apiKey","in":"header","name":"X-Credits-Token","description":"Lightning prepaid credits token from POST /v1/credits (1 sat = 1 item)."}}}}