{"openapi":"3.1.0","info":{"title":"EmailVerify Pro","description":"\n# EmailVerify Pro — World's Best Email Verification API\n\n\n\n**42 signal layers** across syntax, DNS, SMTP, intelligence, and ML.\n\n## Quick Start\n```\nGET /validate?email=brandon@seamlessai.com\n```\n\n## Authentication\nPass your API key in the header:\n```\nX-API-Key: evp_live_your_key_here\n```\nOr as query param: `?api_key=evp_live_your_key_here`\n","version":"6.0.0"},"paths":{"/validate":{"get":{"tags":["Verification"],"summary":"Validate Get","description":"Full email verification — all signal layers.","operationId":"validate_get_validate_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","description":"Email address to verify","title":"Email"},"description":"Email address to verify"},{"name":"smtp","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Smtp"}},{"name":"rbl","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Rbl"}},{"name":"gravatar","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Gravatar"}},{"name":"breach","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Breach"}},{"name":"web_presence","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Web Presence"}},{"name":"domain_age","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Domain Age"}},{"name":"enrich","in":"query","required":false,"schema":{"type":"boolean","description":"Add ML prediction + activity score","default":false,"title":"Enrich"},"description":"Add ML prediction + activity score"},{"name":"suppression","in":"query","required":false,"schema":{"type":"boolean","description":"Check suppression list","default":true,"title":"Suppression"},"description":"Check suppression list"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Verification"],"summary":"Validate Post","description":"Full verification via POST with all options.","operationId":"validate_post_validate_post","parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleReq"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/validate/checks":{"get":{"tags":["Verification"],"summary":"Validate Checks Get","description":"v52: Clean per-check results, ideal for direct DB insert.\nReturns:\n  • summary       — score/grade/can_send/status/primary_risk\n  • checks        — ~45 normalized result strings (smtp: valid|invalid|accept_all|...)\n  • score_breakdown — which checks moved the deliverability score","operationId":"validate_checks_get_validate_checks_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","description":"Email address to verify","title":"Email"},"description":"Email address to verify"},{"name":"smtp","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Smtp"}},{"name":"rbl","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Rbl"}},{"name":"gravatar","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Gravatar"}},{"name":"breach","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Breach"}},{"name":"web_presence","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Web Presence"}},{"name":"domain_age","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Domain Age"}},{"name":"suppression","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Suppression"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Verification"],"summary":"Validate Checks Post","description":"v52: Clean per-check results via POST. See GET /validate/checks for shape.","operationId":"validate_checks_post_validate_checks_post","parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleReq"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/validate/quick":{"get":{"tags":["Verification"],"summary":"Validate Quick","description":"Instant check — syntax + DNS + intelligence only (no SMTP, <100ms).","operationId":"validate_quick_validate_quick_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/validate/syntax":{"get":{"tags":["Verification"],"summary":"Validate Syntax Only","description":"Pure syntax check — RFC 5321/5322 compliance, typo detection, IDN. No network.","operationId":"validate_syntax_only_validate_syntax_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/validate/fast":{"get":{"tags":["Verification"],"summary":"Validate Fast","description":"v53/#5 + v54: Sub-100ms p95 cache-only lookup. Respects per-row TTL by default:\n  • catch-all results cached 12 months (stable behavior)\n  • valid/invalid results cached 7 days  (mailboxes change)\n  • unknown/errors cached 1 day          (re-probe quickly)\nPass max_age_hours to enforce a tighter window. Returns 404 if no fresh cached\nresult — call /validate for a fresh verification.","operationId":"validate_fast_validate_fast_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","description":"Email address — cache-only lookup","title":"Email"},"description":"Email address — cache-only lookup"},{"name":"max_age_hours","in":"query","required":false,"schema":{"type":"integer","maximum":8784,"minimum":1,"description":"Optional: cap cache age. Omit to use per-row TTL (12mo for catch-all, 7d for valid/invalid, 1d for unknown).","title":"Max Age Hours"},"description":"Optional: cap cache age. Omit to use per-row TTL (12mo for catch-all, 7d for valid/invalid, 1d for unknown)."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/validate/bulk":{"post":{"tags":["Verification"],"summary":"Validate Bulk","description":"Sync bulk verification up to 100 emails.","operationId":"validate_bulk_validate_bulk_post","parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkReq"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/validate/bulk/async":{"post":{"tags":["Verification"],"summary":"Validate Bulk Async","description":"Async bulk verification — returns job_id immediately, poll /jobs/{id}.","operationId":"validate_bulk_async_validate_bulk_async_post","parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkReq"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/validate/bulk/turbo":{"post":{"tags":["Verification"],"summary":"Validate Bulk Turbo","description":"v53/#3: Turbo bulk path — cache-first + domain coalescing + 50× concurrency.\n\nPipeline:\n  1. Look up all N emails in cache. Hits return immediately (~50ms each).\n  2. Group cache misses by domain. For each unique domain, run domain-level\n     checks ONCE (MX/RBL/DBL/catch-all) and share the result across all\n     emails at that domain.\n  3. Final per-email check (syntax + SMTP + pattern) runs concurrently\n     at 50× parallelism, gated by per-domain rate limits.\n\nSpeedup is roughly proportional to (cache hit rate + domain duplication ratio).\nA typical 100K customer list with 3K unique domains and 60% cache hit rate\nfinishes in 3-8 minutes instead of 8+ hours.\n\nReturns: same shape as /validate/bulk (synchronous, results array).\nLimit: 5000 emails per call (use /validate/bulk/async with webhook_url for larger).","operationId":"validate_bulk_turbo_validate_bulk_turbo_post","parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkReq"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs/{job_id}":{"get":{"tags":["Jobs"],"summary":"Get Job","description":"Poll async bulk job status. v56: falls back to Postgres for jobs that\nwere evicted from memory (e.g. after container restart).","operationId":"get_job_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs/{job_id}/dead-letter":{"get":{"tags":["Jobs"],"summary":"Get Dead Letter","description":"v55: List emails that failed all retry attempts (dead-letter queue).\nReturns the email list + per-email error + attempt counts. Use POST\n/jobs/{id}/retry-dead-letter to re-queue them as a child job.","operationId":"get_dead_letter_jobs__job_id__dead_letter_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs/{job_id}/retry-dead-letter":{"post":{"tags":["Jobs"],"summary":"Retry Dead Letter","description":"v55: Re-queue dead-letter emails from a previous job as a NEW child job.\nThe child job inherits the parent's options and gets a fresh retry budget.\nReturns the new job_id; poll /jobs/{new_id} as usual.","operationId":"retry_dead_letter_jobs__job_id__retry_dead_letter_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/clerk/me":{"get":{"tags":["Auth"],"summary":"Clerk Me","description":"Return the currently signed-in user (or 401). Enforces Seamless allowlist.","operationId":"clerk_me_auth_clerk_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/clerk/config":{"get":{"tags":["Auth"],"summary":"Clerk Config","description":"Public Clerk config — safe to expose to the browser.","operationId":"clerk_config_auth_clerk_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/me/usage":{"get":{"tags":["Account"],"summary":"Me Usage","description":"v59: current-user usage summary for the customer dashboard.\nReturns: total verifications today + this month + this year, with deltas vs\nprevious period and a 30-day daily histogram.","operationId":"me_usage_me_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/me/stats":{"get":{"tags":["Account"],"summary":"Me Stats","description":"v59: quality breakdown of recent verifications + top domains.","operationId":"me_stats_me_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/me/recent-verifications":{"get":{"tags":["Account"],"summary":"Me Recent Verifications","description":"v59: paginated recent verifications, latest first.","operationId":"me_recent_verifications_me_recent_verifications_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/me/verification/{verification_id}":{"get":{"tags":["Account"],"summary":"Me Verification Detail","description":"v59: full /validate/checks-style detail for one verification (modal popup).","operationId":"me_verification_detail_me_verification__verification_id__get","parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"integer","title":"Verification Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs/{job_id}/resume":{"post":{"tags":["Jobs"],"summary":"Resume Failed Emails","description":"Re-queue ONLY the failed emails from a previous job into a new child job.\nReturns the new job_id. Useful when transient errors (network, rate-limit)\ncaused a subset of emails to fail in the original run.","operationId":"resume_failed_emails_jobs__job_id__resume_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/dns":{"get":{"tags":["Signals"],"summary":"Check Dns Only","description":"DNS/MX/SPF/DMARC lookup for a domain.","operationId":"check_dns_only_check_dns_get","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/dkim":{"get":{"tags":["Signals"],"summary":"Check Dkim","description":"Check DKIM records for a domain.","operationId":"check_dkim_check_dkim_get","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/rbl":{"get":{"tags":["Signals"],"summary":"Check Rbl Endpoint","description":"Check an MX host's IP against all RBL blacklists.","operationId":"check_rbl_endpoint_check_rbl_get","parameters":[{"name":"mx_host","in":"query","required":true,"schema":{"type":"string","title":"Mx Host"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/mx-intel":{"get":{"tags":["Signals"],"summary":"Check Mx Intel","description":"Full MX infrastructure analysis — PTR, hosting provider, geo, chain.","operationId":"check_mx_intel_check_mx_intel_get","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/domain-age":{"get":{"tags":["Signals"],"summary":"Check Domain Age Endpoint","description":"Domain age via certificate transparency logs (crt.sh).","operationId":"check_domain_age_endpoint_check_domain_age_get","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/pattern":{"get":{"tags":["Signals"],"summary":"Check Pattern","description":"Pattern analysis — human-likeness score, name detection, random string detection.","operationId":"check_pattern_check_pattern_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/activity":{"get":{"tags":["Signals"],"summary":"Check Activity","description":"Email activity score — estimates how recently active the account is.","operationId":"check_activity_check_activity_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/suppression/check":{"get":{"tags":["Suppression"],"summary":"Suppression Check","description":"Check if email is on the suppression list.","operationId":"suppression_check_suppression_check_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/suppression/add":{"post":{"tags":["Suppression"],"summary":"Suppression Add","description":"Add email to suppression list.","operationId":"suppression_add_suppression_add_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionAddReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/suppression/{email}":{"delete":{"tags":["Suppression"],"summary":"Suppression Remove","description":"Remove email from suppression list.","operationId":"suppression_remove_suppression__email__delete","parameters":[{"name":"email","in":"path","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/suppression/stats":{"get":{"tags":["Suppression"],"summary":"Suppression Stats","description":"Suppression list statistics.","operationId":"suppression_stats_suppression_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/bounce":{"post":{"tags":["Feedback"],"summary":"Record Bounce","description":"Record a real delivery bounce. Auto-trains ML classifier.","operationId":"record_bounce_bounce_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BounceReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/delivered":{"post":{"tags":["Feedback"],"summary":"Record Delivered","description":"Record a successful delivery. Adds positive training sample to ML.","operationId":"record_delivered_delivered_post","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/received":{"post":{"tags":["Feedback"],"summary":"Record Received","description":"Mark an email as confirmed-received (appeared in inbox).\nGround-truth signal: mailbox exists, person is real.\nFuture /validate calls for this address get +25 confirmed_received bonus,\nbypassing catch-all penalties.","operationId":"record_received_received_post","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","default":"inbox","title":"Source"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/received/batch":{"post":{"tags":["Feedback"],"summary":"Record Received Batch","description":"Mark multiple emails as confirmed-received in one call.\n\nAccepts two formats:\n  Old: {\"emails\": [\"a@b.com\", ...], \"source\": \"inbox\"}\n  New: {\"senders\": [{\"email\": \"a@b.com\", \"received_at\": \"Mon, May 2, 2026, 9:10 AM\",\n                      \"subject\": \"Re: your message\"}], \"source\": \"inbox\"}\n\nreceived_at can be a Unix timestamp (float) or a human-readable date string.\nReturns count of emails recorded plus domain_inbox_stats summary.","operationId":"record_received_batch_received_batch_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ml/stats":{"get":{"tags":["ML"],"summary":"Ml Stats","description":"ML model statistics and training status.","operationId":"ml_stats_ml_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ml/train":{"post":{"tags":["ML"],"summary":"Ml Train","description":"Train/retrain the proprietary deliverability model from bounce data.","operationId":"ml_train_ml_train_post","parameters":[{"name":"min_samples","in":"query","required":false,"schema":{"type":"integer","default":1000,"title":"Min Samples"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stats":{"get":{"tags":["Analytics"],"summary":"Stats","description":"Real-time verification analytics dashboard.","operationId":"stats_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/stats/domains":{"get":{"tags":["Analytics"],"summary":"Domain Stats","description":"Domain learning registry — catch-all status, email formats.","operationId":"domain_stats_stats_domains_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/stats/store":{"get":{"tags":["Analytics"],"summary":"Store Stats","description":"Persistence layer statistics.","operationId":"store_stats_stats_store_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"tags":["System"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/greylist":{"get":{"tags":["System"],"summary":"Greylist","operationId":"greylist_greylist_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/senders":{"get":{"tags":["System"],"summary":"Senders","operationId":"senders_senders_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ips":{"get":{"tags":["System"],"summary":"Ips","operationId":"ips_ips_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/webhooks/stats":{"get":{"tags":["System"],"summary":"Webhook Stats","operationId":"webhook_stats_webhooks_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin/update-intelligence":{"post":{"tags":["Admin"],"summary":"Update Intelligence","description":"Refresh disposable/free provider databases from live sources.","operationId":"update_intelligence_admin_update_intelligence_post","parameters":[{"name":"force","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Force"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/reverify":{"post":{"tags":["Admin"],"summary":"Trigger Reverify","description":"Trigger re-verification of stale email records.","operationId":"trigger_reverify_admin_reverify_post","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status","title":"Status"},"description":"Filter by status"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"webhook_url","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/keys":{"get":{"tags":["API Keys"],"summary":"List Keys","operationId":"list_keys_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["API Keys"],"summary":"Create Key","description":"Create a new API key. Save the key — it won't be shown again.","operationId":"create_key_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyCreateReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/keys/{key_id}":{"delete":{"tags":["API Keys"],"summary":"Revoke Key","operationId":"revoke_key_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/utils/dedup":{"post":{"tags":["Utilities"],"summary":"Dedup Emails","description":"Deduplicate a list of emails (Gmail dots, plus addressing, case normalization).","operationId":"dedup_emails_utils_dedup_post","requestBody":{"content":{"application/json":{"schema":{"items":{"type":"string"},"type":"array","title":"Emails"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/verify/quick":{"get":{"tags":["Verification"],"summary":"Verify Quick","description":"Sub-50ms email verification for form validation. Returns instantly with\ncached/syntax signals. Queues full SMTP verification in background.","operationId":"verify_quick_verify_quick_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"webhook_url","in":"query","required":false,"schema":{"type":"string","default":"","title":"Webhook Url"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/verify/status/{verification_id}":{"get":{"tags":["Verification"],"summary":"Verify Status","description":"Poll for result of a pending quick verification.","operationId":"verify_status_verify_status__verification_id__get","parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/verify/typo":{"get":{"tags":["Verification"],"summary":"Check Typo","description":"Detect email typos and return correction suggestion.","operationId":"check_typo_verify_typo_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/find-email/v2":{"post":{"tags":["Email Finder"],"summary":"Find Email V2 Endpoint","description":"Advanced email finder. >70% find rate on Fortune 1000. Uses 5 credits.","operationId":"find_email_v2_endpoint_find_email_v2_post","parameters":[{"name":"first_name","in":"query","required":true,"schema":{"type":"string","title":"First Name"}},{"name":"last_name","in":"query","required":true,"schema":{"type":"string","title":"Last Name"}},{"name":"domain","in":"query","required":true,"schema":{"type":"string","title":"Domain"}},{"name":"company_name","in":"query","required":false,"schema":{"type":"string","default":"","title":"Company Name"}},{"name":"do_smtp","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Do Smtp"}},{"name":"do_scrape","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Do Scrape"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/db/lookup":{"get":{"tags":["Database"],"summary":"Db Lookup","description":"Look up a previous verification result from the database.","operationId":"db_lookup_db_lookup_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/db/search":{"get":{"tags":["Database"],"summary":"Db Search","description":"Search verification history.","operationId":"db_search_db_search_get","parameters":[{"name":"domain","in":"query","required":false,"schema":{"type":"string","default":"","title":"Domain"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","default":"","title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/db/stats":{"get":{"tags":["Database"],"summary":"Db Stats","description":"Overall database statistics.","operationId":"db_stats_db_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/db/domain/{domain}":{"get":{"tags":["Database"],"summary":"Db Domain Stats","description":"Statistics for a specific domain.","operationId":"db_domain_stats_db_domain__domain__get","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cache/stats":{"get":{"tags":["Infrastructure"],"summary":"Cache Stats Endpoint","description":"Redis cache statistics.","operationId":"cache_stats_endpoint_cache_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ip-pool/status":{"get":{"tags":["Infrastructure"],"summary":"Ip Pool Status","description":"IP pool and warmup status.","operationId":"ip_pool_status_ip_pool_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ip-pool/register":{"post":{"tags":["Infrastructure"],"summary":"Ip Pool Register","description":"Register a new IP in the warmup program.","operationId":"ip_pool_register_ip_pool_register_post","parameters":[{"name":"ip","in":"query","required":true,"schema":{"type":"string","title":"Ip"}},{"name":"pool","in":"query","required":false,"schema":{"type":"string","default":"general","title":"Pool"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/sender-domains":{"get":{"tags":["Infrastructure"],"summary":"Sender Domains Status","description":"Sender domain warmup status.","operationId":"sender_domains_status_sender_domains_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/sender-domains/register":{"post":{"tags":["Infrastructure"],"summary":"Sender Domain Register","description":"Register a new sender domain.","operationId":"sender_domain_register_sender_domains_register_post","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/bounce/postmark":{"post":{"tags":["Bounce Processing"],"summary":"Bounce Postmark","description":"Process Postmark bounce webhook and update database.","operationId":"bounce_postmark_bounce_postmark_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Payload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/bounce/sendgrid":{"post":{"tags":["Bounce Processing"],"summary":"Bounce Sendgrid","description":"Process SendGrid bounce events and update database.","operationId":"bounce_sendgrid_bounce_sendgrid_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_bounce_sendgrid_bounce_sendgrid_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/bounce/ses":{"post":{"tags":["Bounce Processing"],"summary":"Bounce Ses","description":"Process AWS SES bounce notification.","operationId":"bounce_ses_bounce_ses_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Payload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/bounce/stats":{"get":{"tags":["Bounce Processing"],"summary":"Bounce Stats","description":"Bounce statistics from feedback loop.","operationId":"bounce_stats_bounce_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ml/stats/v2":{"get":{"tags":["ML"],"summary":"Ml Stats V2","description":"Proprietary ML model statistics.","operationId":"ml_stats_v2_ml_stats_v2_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/activity":{"get":{"tags":["Enrichment"],"summary":"Activity Profile","description":"Compute email activity profile from cached verification result.","operationId":"activity_profile_activity_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/deliverability/domain/{domain}":{"get":{"tags":["Deliverability"],"summary":"Domain Deliverability","description":"Comprehensive deliverability health check for a domain.","operationId":"domain_deliverability_deliverability_domain__domain__get","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/verify/microsoft-graph":{"get":{"tags":["Provider Checks"],"summary":"Verify Microsoft Graph","description":"Check email existence via Microsoft Graph API (requires OAuth credentials).","operationId":"verify_microsoft_graph_verify_microsoft_graph_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"tenant_id","in":"query","required":false,"schema":{"type":"string","default":"","title":"Tenant Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/verify/google-workspace":{"get":{"tags":["Provider Checks"],"summary":"Verify Google Workspace","description":"Check email existence via Google Workspace Directory API (requires service account).","operationId":"verify_google_workspace_verify_google_workspace_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/verify/catchall-resolve":{"post":{"tags":["Verification"],"summary":"Catchall Resolve V2","description":"Resolve catch-all domains using multi-signal triangulation.\nUses LinkedIn, GitHub, website scraping, historical DB, format probability.","operationId":"catchall_resolve_v2_verify_catchall_resolve_post","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"first_name","in":"query","required":false,"schema":{"type":"string","default":"","title":"First Name"}},{"name":"last_name","in":"query","required":false,"schema":{"type":"string","default":"","title":"Last Name"}},{"name":"company_name","in":"query","required":false,"schema":{"type":"string","default":"","title":"Company Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/verify/breach-intel":{"get":{"tags":["Verification"],"summary":"Breach Intelligence Endpoint","description":"Multi-source breach intelligence (HIBP + optional SpyCloud/Dehashed).","operationId":"breach_intelligence_endpoint_verify_breach_intel_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/plans":{"get":{"tags":["Billing"],"summary":"Billing Plans","description":"Available subscription plans.","operationId":"billing_plans_billing_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/billing/signup":{"post":{"tags":["Billing"],"summary":"Billing Signup","description":"Create a new customer account with API key.","operationId":"billing_signup_billing_signup_post","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"plan","in":"query","required":false,"schema":{"type":"string","default":"free","title":"Plan"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/checkout/{plan}":{"get":{"tags":["Billing"],"summary":"Billing Checkout","description":"Create Stripe checkout session for a plan upgrade.","operationId":"billing_checkout_billing_checkout__plan__get","parameters":[{"name":"plan","in":"path","required":true,"schema":{"type":"string","title":"Plan"}},{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/stripe-webhook":{"post":{"tags":["Billing"],"summary":"Billing Stripe Webhook","description":"Handle Stripe subscription lifecycle webhooks.","operationId":"billing_stripe_webhook_billing_stripe_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/billing/usage/{customer_id}":{"get":{"tags":["Billing"],"summary":"Billing Usage","description":"Get usage stats for a customer.","operationId":"billing_usage_billing_usage__customer_id__get","parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","title":"Customer Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrations/klaviyo/sync":{"post":{"tags":["Integrations"],"summary":"Klaviyo Sync","description":"Sync verification results to Klaviyo profiles.","operationId":"klaviyo_sync_integrations_klaviyo_sync_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_klaviyo_sync_integrations_klaviyo_sync_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrations/activecampaign/sync":{"post":{"tags":["Integrations"],"summary":"Activecampaign Sync","description":"Sync verification results to ActiveCampaign contacts.","operationId":"activecampaign_sync_integrations_activecampaign_sync_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_activecampaign_sync_integrations_activecampaign_sync_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrations/make/send":{"post":{"tags":["Integrations"],"summary":"Make Send","description":"Send verification result to a Make (Integromat) webhook.","operationId":"make_send_integrations_make_send_post","parameters":[{"name":"webhook_url","in":"query","required":true,"schema":{"type":"string","title":"Webhook Url"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Result"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/compliance/summary":{"get":{"tags":["Compliance"],"summary":"Compliance Summary","description":"SOC 2 compliance summary and audit trail statistics.","operationId":"compliance_summary_compliance_summary_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/compliance/audit-trail":{"get":{"tags":["Compliance"],"summary":"Compliance Audit","description":"Query the SOC 2 audit trail.","operationId":"compliance_audit_compliance_audit_trail_get","parameters":[{"name":"customer_id","in":"query","required":false,"schema":{"type":"string","default":"","title":"Customer Id"}},{"name":"control","in":"query","required":false,"schema":{"type":"string","default":"","title":"Control"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/compliance/customer-data/{customer_id}":{"delete":{"tags":["Compliance"],"summary":"Compliance Erase","description":"GDPR/CCPA right-to-erasure — delete all customer data.","operationId":"compliance_erase_compliance_customer_data__customer_id__delete","parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","title":"Customer Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/regions":{"get":{"tags":["Infrastructure"],"summary":"Regions Config","description":"Multi-region configuration and routing rules.","operationId":"regions_config_regions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/regions/health":{"get":{"tags":["Infrastructure"],"summary":"Regions Health","description":"Health status of all configured regions.","operationId":"regions_health_regions_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/regions/route":{"get":{"tags":["Infrastructure"],"summary":"Regions Route","description":"Determine which region should handle this email.","operationId":"regions_route_regions_route_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"client_country","in":"query","required":false,"schema":{"type":"string","default":"","title":"Client Country"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/benchmark/run":{"post":{"tags":["Benchmark"],"summary":"Benchmark Run","description":"Run accuracy benchmark. test_emails: [{email, expected_status, notes}]","operationId":"benchmark_run_benchmark_run_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_benchmark_run_benchmark_run_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/benchmark/report/{benchmark_id}":{"get":{"tags":["Benchmark"],"summary":"Benchmark Report Md","description":"Return benchmark results as publishable markdown report.","operationId":"benchmark_report_md_benchmark_report__benchmark_id__get","parameters":[{"name":"benchmark_id","in":"path","required":true,"schema":{"type":"string","title":"Benchmark Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/domain-intel/{domain}":{"get":{"tags":["Intelligence"],"summary":"Get Domain Intel","description":"Return all pre-cached non-SMTP intelligence for a domain.\nUsed by dashboard to show enrichment data alongside live verification.\nPublic endpoint (no auth) — only returns metadata, no PII.","operationId":"get_domain_intel_domain_intel__domain__get","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/domain-intel/stats":{"get":{"tags":["Admin"],"summary":"Admin Domain Intel Stats","description":"Aggregate stats over the entire domain_intel cache. Admin only.","operationId":"admin_domain_intel_stats_admin_domain_intel_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/gdpr/erase":{"delete":{"tags":["GDPR / CCPA"],"summary":"Gdpr Erase","description":"Right to Erasure (GDPR Art. 17 / CCPA).\nDeletes all stored PII for this email address.\nHard bounce + spam complaint suppressions are retained for legal compliance.","operationId":"gdpr_erase_gdpr_erase_delete","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/gdpr/export":{"get":{"tags":["GDPR / CCPA"],"summary":"Gdpr Export","description":"Right of Access (GDPR Art. 15).\nReturns all data stored about this email address.","operationId":"gdpr_export_gdpr_export_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/gdpr/domain":{"delete":{"tags":["GDPR / CCPA"],"summary":"Gdpr Erase Domain","description":"Erase all stored data for an entire domain.","operationId":"gdpr_erase_domain_gdpr_domain_delete","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/gdpr/purge":{"post":{"tags":["GDPR / CCPA"],"summary":"Gdpr Purge","description":"Purge all records older than retention policy.\nRun this daily. Results older than 90 days are deleted automatically.","operationId":"gdpr_purge_gdpr_purge_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/gdpr/status":{"get":{"tags":["GDPR / CCPA"],"summary":"Gdpr Status","description":"GDPR compliance dashboard — erasure requests, data stores, retention policy.","operationId":"gdpr_status_gdpr_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/resolve-catchall":{"post":{"tags":["Catch-All Resolution"],"summary":"Resolve Catchall Endpoint","description":"Resolve a catch-all email to valid or invalid.\nRuns all available signals: MS GetCredentialType, LinkedIn, Twitter,\nHIBP, Gravatar, format probability, domain cohort, ML classifier.","operationId":"resolve_catchall_endpoint_resolve_catchall_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatchAllResolveReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/name-realism":{"get":{"tags":["Signals"],"summary":"Check Name Realism","description":"Score how realistic a name this email represents (0-100).","operationId":"check_name_realism_check_name_realism_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/format-probability":{"get":{"tags":["Signals"],"summary":"Check Format Probability","description":"Score format probability for this email at its domain.","operationId":"check_format_probability_check_format_probability_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/ms-credential":{"get":{"tags":["Signals"],"summary":"Check Ms Credential Endpoint","description":"Microsoft GetCredentialType — confirms M365 user existence.","operationId":"check_ms_credential_endpoint_check_ms_credential_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/cross-reference":{"post":{"tags":["Signals"],"summary":"Check Cross Reference","description":"Cross-reference email against Hunter.io, Apollo, Clearbit, etc.","operationId":"check_cross_reference_check_cross_reference_post","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/mine-emails":{"post":{"tags":["Signals"],"summary":"Mine Emails Endpoint","description":"Mine public sources for real emails at a domain to build format DB.","operationId":"mine_emails_endpoint_check_mine_emails_post","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","title":"Domain"}},{"name":"use_github","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Use Github"}},{"name":"use_web","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Use Web"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/feedback/report":{"post":{"tags":["Feedback"],"summary":"Feedback Report","description":"Report a verification result as correct/incorrect. Trains the classifier.","operationId":"feedback_report_feedback_report_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/feedback/opened":{"post":{"tags":["Feedback"],"summary":"Feedback Opened","description":"Record email open (tracking pixel). Definitive proof of valid + active email.","operationId":"feedback_opened_feedback_opened_post","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","default":"tracking_pixel","title":"Source"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/feedback/clicked":{"post":{"tags":["Feedback"],"summary":"Feedback Clicked","description":"Record link click. Strongest proof of valid + active email.","operationId":"feedback_clicked_feedback_clicked_post","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"link","in":"query","required":false,"schema":{"type":"string","default":"","title":"Link"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/feedback/accuracy":{"get":{"tags":["Feedback"],"summary":"Feedback Accuracy","description":"Verification accuracy statistics from all feedback data.","operationId":"feedback_accuracy_feedback_accuracy_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/cohort/{domain}":{"get":{"tags":["Domain Cohort"],"summary":"Get Domain Cohort","description":"Get verification history and accuracy for a specific domain.","operationId":"get_domain_cohort_cohort__domain__get","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cohort":{"get":{"tags":["Domain Cohort"],"summary":"List Cohorts","description":"List all domains with sufficient feedback data.","operationId":"list_cohorts_cohort_get","parameters":[{"name":"min_feedback","in":"query","required":false,"schema":{"type":"integer","default":3,"title":"Min Feedback"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/catchall-classifier/stats":{"get":{"tags":["Catch-All Resolution"],"summary":"Catchall Classifier Stats","description":"Catch-all ML classifier statistics.","operationId":"catchall_classifier_stats_catchall_classifier_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/catchall-classifier/train":{"post":{"tags":["Catch-All Resolution"],"summary":"Catchall Classifier Train","description":"Manually trigger catch-all classifier retraining.","operationId":"catchall_classifier_train_catchall_classifier_train_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/check/scrape-domain":{"get":{"tags":["Signals"],"summary":"Scrape Domain Endpoint","description":"Deep web crawl with anti-detection stack (curl_cffi → cloudscraper → Playwright → Wayback).\n\nReturns four types of intelligence per domain:\n\n**Email detection** — emails found, extraction method, page source URL, surrounding context\n**Email pattern** — dominant format (first.last / flast / f.last), confidence, distribution, examples\n**Name detection** — people found with first/last name, job title, source page, associated email/phone\n**Phone detection** — phones found, normalized E.164 format, page source, country code, toll-free flag\n\nAll results are cached 7 days per domain.\nAnti-detection: TLS fingerprint impersonation, Cloudflare bypass, headless Chrome stealth, Wayback fallback.","operationId":"scrape_domain_endpoint_check_scrape_domain_get","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","description":"Domain to crawl (e.g. stripe.com)","title":"Domain"},"description":"Domain to crawl (e.g. stripe.com)"},{"name":"email","in":"query","required":false,"schema":{"type":"string","description":"Optional target email to find exactly","default":"","title":"Email"},"description":"Optional target email to find exactly"},{"name":"max_pages","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Max Pages"}},{"name":"include_details","in":"query","required":false,"schema":{"type":"boolean","description":"Include per-email/phone/person detail objects","default":true,"title":"Include Details"},"description":"Include per-email/phone/person detail objects"},{"name":"use_cache","in":"query","required":false,"schema":{"type":"boolean","description":"Return cached result if available (set false to force re-crawl)","default":true,"title":"Use Cache"},"description":"Return cached result if available (set false to force re-crawl)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/linkedin-name":{"get":{"tags":["Signals"],"summary":"Linkedin Name Check Endpoint","description":"Check if the person's name from an email appears on LinkedIn at that company.\n\nExtracts first/last name from the email local part, then searches:\n1. LinkedIn people search (direct)\n2. LinkedIn company people page\n3. LinkedIn profile slug inference (tries common patterns)\n4. Google search: site:linkedin.com \"John Smith\" \"Stripe\"\n5. Bing search fallback\n6. DuckDuckGo fallback\n\nReturns `target_name_linkedin_found: true` when the person is confirmed\nto work at the company — a strong secondary signal for catch-all validation.\n\nOnly works with name-pattern emails (first.last, first_last, f.last).","operationId":"linkedin_name_check_endpoint_check_linkedin_name_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","description":"Email to check (e.g. john.smith@stripe.com)","title":"Email"},"description":"Email to check (e.g. john.smith@stripe.com)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/bulk/upload":{"post":{"tags":["Bulk"],"summary":"Bulk Upload","description":"Upload CSV/Excel/TXT list for bulk verification. Returns job_id to poll.","operationId":"bulk_upload_bulk_upload_post","parameters":[{"name":"do_smtp","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Do Smtp"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_bulk_upload_bulk_upload_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/bulk/status/{job_id}":{"get":{"tags":["Bulk"],"summary":"Bulk Status","description":"Get real-time status and stats for a bulk job.","operationId":"bulk_status_bulk_status__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/bulk/download/{job_id}":{"get":{"tags":["Bulk"],"summary":"Bulk Download","description":"Download results as CSV. filter: all/valid/invalid/accept_all/disposable","operationId":"bulk_download_bulk_download__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","default":"","title":"Filter"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/bulk/jobs":{"get":{"tags":["Bulk"],"summary":"Bulk List Jobs","description":"List recent bulk jobs.","operationId":"bulk_list_jobs_bulk_jobs_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/score":{"get":{"tags":["Deliverability"],"summary":"Get Deliverability Score","description":"Get 0-100 deliverability score for an email with full breakdown.","operationId":"get_deliverability_score_score_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/find-email":{"post":{"tags":["Email Finder"],"summary":"Find Email Endpoint","description":"Find the most likely email for a person at a company.\nInput: first_name, last_name, domain\nReturns ranked candidates with confidence scores.","operationId":"find_email_endpoint_find_email_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindEmailReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/domain-formats":{"get":{"tags":["Domain Intelligence"],"summary":"List Domain Formats","description":"List all known domain email formats with confidence scores.","operationId":"list_domain_formats_domain_formats_get","parameters":[{"name":"min_confidence","in":"query","required":false,"schema":{"type":"number","default":0.7,"title":"Min Confidence"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/domain-formats/{domain}":{"get":{"tags":["Domain Intelligence"],"summary":"Get Domain Format Endpoint","description":"Get the known email format for a specific domain.","operationId":"get_domain_format_endpoint_domain_formats__domain__get","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/domain-formats/scrape":{"post":{"tags":["Domain Intelligence"],"summary":"Scrape Domain Format","description":"Trigger proactive scraping of a domain to learn its email format.","operationId":"scrape_domain_format_domain_formats_scrape_post","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/usage":{"get":{"tags":["Account"],"summary":"Get Usage","description":"Get credit usage stats for the current billing period.","operationId":"get_usage_usage_get","parameters":[{"name":"key_id","in":"query","required":false,"schema":{"type":"string","default":"default","title":"Key Id"}},{"name":"tier","in":"query","required":false,"schema":{"type":"string","default":"free","title":"Tier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/plans":{"get":{"tags":["Account"],"summary":"Get Plans","description":"Return all available plans and their limits.","operationId":"get_plans_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin/update-disposable":{"post":{"tags":["Admin"],"summary":"Update Disposable","description":"Trigger pull of fresh disposable domain lists from public sources.","operationId":"update_disposable_admin_update_disposable_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin/disposable-stats":{"get":{"tags":["Admin"],"summary":"Disposable Stats","description":"Get stats from the last disposable domain update.","operationId":"disposable_stats_admin_disposable_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/webhooks/sendgrid":{"post":{"tags":["ESP Integrations"],"summary":"Sendgrid Webhook","description":"Receive SendGrid event webhooks (bounce/delivered/open/click).","operationId":"sendgrid_webhook_webhooks_sendgrid_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/webhooks/mailchimp":{"post":{"tags":["ESP Integrations"],"summary":"Mailchimp Webhook","description":"Receive Mailchimp webhooks (bounce/unsubscribe/complaint).","operationId":"mailchimp_webhook_webhooks_mailchimp_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/webhooks/postmark":{"post":{"tags":["ESP Integrations"],"summary":"Postmark Webhook","description":"Receive Postmark bounce/delivery webhooks.","operationId":"postmark_webhook_webhooks_postmark_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/webhooks/ses":{"post":{"tags":["ESP Integrations"],"summary":"Ses Webhook","description":"Receive Amazon SES bounce/complaint notifications via SNS.","operationId":"ses_webhook_webhooks_ses_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/integrations/hubspot/sync":{"post":{"tags":["ESP Integrations"],"summary":"Hubspot Sync","description":"Update a HubSpot contact with email verification score.","operationId":"hubspot_sync_integrations_hubspot_sync_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HubSpotSyncReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrations/salesforce/sync":{"post":{"tags":["ESP Integrations"],"summary":"Salesforce Sync","description":"Update a Salesforce Lead/Contact EmailScore__c field.","operationId":"salesforce_sync_integrations_salesforce_sync_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HubSpotSyncReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrations/zapier/send":{"post":{"tags":["ESP Integrations"],"summary":"Zapier Send","description":"Forward a verification result to a Zapier webhook URL.","operationId":"zapier_send_integrations_zapier_send_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/integrations/status":{"get":{"tags":["ESP Integrations"],"summary":"Integrations Status","description":"Check which integrations are configured.","operationId":"integrations_status_integrations_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/integrations":{"get":{"tags":["Integrations"],"summary":"List Integrations Ep","description":"List all configured ESP/CRM integrations.","operationId":"list_integrations_ep_integrations_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["Integrations"],"summary":"Create Integration","description":"Configure a new ESP/CRM integration.","operationId":"create_integration_integrations_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrations/{integration_id}":{"delete":{"tags":["Integrations"],"summary":"Delete Integration","description":"Remove an integration.","operationId":"delete_integration_integrations__integration_id__delete","parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","title":"Integration Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrations/{integration_id}/events":{"get":{"tags":["Integrations"],"summary":"Integration Events","description":"Get recent delivery events for an integration.","operationId":"integration_events_integrations__integration_id__events_get","parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","title":"Integration Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrations/test":{"post":{"tags":["Integrations"],"summary":"Test Integration","description":"Test an integration with a sample payload before saving.","operationId":"test_integration_integrations_test_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/bulk/{job_id}/report":{"get":{"tags":["Bulk"],"summary":"Bulk Health Report","description":"Get comprehensive list health report with recommendations.","operationId":"bulk_health_report_bulk__job_id__report_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/validate/with-score":{"get":{"tags":["Validate"],"summary":"Validate With Score","description":"Verify email AND return 0-100 deliverability score in one call.","operationId":"validate_with_score_validate_with_score_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/request":{"post":{"tags":["Auth"],"summary":"Auth Request Magic Link","description":"Request a magic login link. Sends email with one-time sign-in URL.\nRate limited to 5 requests/minute per IP.","operationId":"auth_request_magic_link_auth_request_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MagicRequestBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/verify":{"post":{"tags":["Auth"],"summary":"Auth Verify Post","description":"POST handler for programmatic token verification.","operationId":"auth_verify_post_auth_verify_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MagicVerifyBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/me":{"get":{"tags":["Auth"],"summary":"Auth Me","description":"Get current user info from session token or API key.","operationId":"auth_me_auth_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/logout":{"post":{"tags":["Auth"],"summary":"Auth Logout","description":"Invalidate session token.","operationId":"auth_logout_auth_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin/domain-learning/stats":{"get":{"tags":["Admin"],"summary":"Admin Domain Learning Stats","description":"Domain learning cache stats. Requires X-Admin-Secret.","operationId":"admin_domain_learning_stats_admin_domain_learning_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin/users":{"get":{"tags":["Admin"],"summary":"Admin List Users","description":"List all users. Requires X-Admin-Secret header.","operationId":"admin_list_users_admin_users_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/users/{email}/upgrade":{"post":{"tags":["Admin"],"summary":"Admin Upgrade User","description":"Manually upgrade a user's plan. Requires X-Admin-Secret header.","operationId":"admin_upgrade_user_admin_users__email__upgrade_post","parameters":[{"name":"email","in":"path","required":true,"schema":{"type":"string","title":"Email"}},{"name":"plan","in":"query","required":true,"schema":{"type":"string","title":"Plan"}},{"name":"credits","in":"query","required":false,"schema":{"type":"integer","title":"Credits"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/infra/blacklist-status":{"get":{"tags":["Infrastructure"],"summary":"Blacklist Status","description":"Current blacklist status for all monitored IPs and domains.","operationId":"blacklist_status_infra_blacklist_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"APIKeyCreateReq":{"properties":{"name":{"type":"string","title":"Name"},"tier":{"type":"string","title":"Tier","default":"free"},"owner_email":{"type":"string","title":"Owner Email","default":""}},"type":"object","required":["name"],"title":"APIKeyCreateReq"},"Body_activecampaign_sync_integrations_activecampaign_sync_post":{"properties":{"results":{"items":{},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"Body_activecampaign_sync_integrations_activecampaign_sync_post"},"Body_benchmark_run_benchmark_run_post":{"properties":{"test_emails":{"items":{},"type":"array","title":"Test Emails"},"providers":{"items":{},"type":"array","title":"Providers"}},"type":"object","required":["test_emails"],"title":"Body_benchmark_run_benchmark_run_post"},"Body_bounce_sendgrid_bounce_sendgrid_post":{"properties":{"events":{"items":{},"type":"array","title":"Events"}},"type":"object","required":["events"],"title":"Body_bounce_sendgrid_bounce_sendgrid_post"},"Body_bulk_upload_bulk_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_bulk_upload_bulk_upload_post"},"Body_klaviyo_sync_integrations_klaviyo_sync_post":{"properties":{"results":{"items":{},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"Body_klaviyo_sync_integrations_klaviyo_sync_post"},"BounceReq":{"properties":{"email":{"type":"string","title":"Email"},"bounce_type":{"type":"string","title":"Bounce Type","default":"hard"},"bounce_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bounce Code"},"bounce_msg":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bounce Msg"},"sending_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sending Domain"}},"type":"object","required":["email"],"title":"BounceReq"},"BulkReq":{"properties":{"emails":{"items":{"type":"string"},"type":"array","title":"Emails"},"smtp":{"type":"boolean","title":"Smtp","default":true},"rbl":{"type":"boolean","title":"Rbl","default":true},"gravatar":{"type":"boolean","title":"Gravatar","default":true},"breach":{"type":"boolean","title":"Breach","default":false},"web_presence":{"type":"boolean","title":"Web Presence","default":true},"domain_age":{"type":"boolean","title":"Domain Age","default":true},"deduplicate":{"type":"boolean","title":"Deduplicate","default":true},"check_suppression":{"type":"boolean","title":"Check Suppression","default":true},"max_concurrent":{"type":"integer","title":"Max Concurrent","default":10},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url"},"hibp_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hibp Api Key"}},"type":"object","required":["emails"],"title":"BulkReq"},"CatchAllResolveReq":{"properties":{"email":{"type":"string","title":"Email"},"do_ms":{"type":"boolean","title":"Do Ms","default":true},"do_linkedin":{"type":"boolean","title":"Do Linkedin","default":false},"do_twitter":{"type":"boolean","title":"Do Twitter","default":false},"do_hibp":{"type":"boolean","title":"Do Hibp","default":false},"do_gravatar":{"type":"boolean","title":"Do Gravatar","default":true},"do_mining":{"type":"boolean","title":"Do Mining","default":false}},"type":"object","required":["email"],"title":"CatchAllResolveReq"},"FeedbackReq":{"properties":{"email":{"type":"string","title":"Email"},"actual_result":{"type":"string","title":"Actual Result"},"feedback_type":{"type":"string","title":"Feedback Type","default":"manual"},"original_verdict":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Verdict"},"original_confidence":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Original Confidence"},"bounce_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bounce Type"},"bounce_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bounce Code"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"}},"type":"object","required":["email","actual_result"],"title":"FeedbackReq"},"FindEmailReq":{"properties":{"first_name":{"type":"string","title":"First Name"},"last_name":{"type":"string","title":"Last Name"},"domain":{"type":"string","title":"Domain"},"do_smtp":{"type":"boolean","title":"Do Smtp","default":true},"do_scrape":{"type":"boolean","title":"Do Scrape","default":true}},"type":"object","required":["first_name","last_name","domain"],"title":"FindEmailReq"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HubSpotSyncReq":{"properties":{"email":{"type":"string","title":"Email"},"score":{"type":"integer","title":"Score"},"status":{"type":"string","title":"Status"},"grade":{"type":"string","title":"Grade","default":"B"}},"type":"object","required":["email","score","status"],"title":"HubSpotSyncReq"},"IntegrationReq":{"properties":{"name":{"type":"string","title":"Name"},"credentials":{"additionalProperties":true,"type":"object","title":"Credentials"},"field_mapping":{"additionalProperties":true,"type":"object","title":"Field Mapping","default":{}},"trigger_on":{"items":{},"type":"array","title":"Trigger On","default":["all"]},"enabled":{"type":"boolean","title":"Enabled","default":true}},"type":"object","required":["name","credentials"],"title":"IntegrationReq"},"MagicRequestBody":{"properties":{"email":{"type":"string","title":"Email"}},"type":"object","required":["email"],"title":"MagicRequestBody"},"MagicVerifyBody":{"properties":{"token":{"type":"string","title":"Token"}},"type":"object","required":["token"],"title":"MagicVerifyBody"},"SingleReq":{"properties":{"email":{"type":"string","title":"Email"},"smtp":{"type":"boolean","title":"Smtp","default":true},"rbl":{"type":"boolean","title":"Rbl","default":true},"gravatar":{"type":"boolean","title":"Gravatar","default":true},"breach":{"type":"boolean","title":"Breach","default":false},"web_presence":{"type":"boolean","title":"Web Presence","default":true},"domain_age":{"type":"boolean","title":"Domain Age","default":true},"dkim":{"type":"boolean","title":"Dkim","default":false},"mx_intel":{"type":"boolean","title":"Mx Intel","default":false},"enrich":{"type":"boolean","title":"Enrich","default":false},"check_suppression":{"type":"boolean","title":"Check Suppression","default":true},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url"},"hibp_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hibp Api Key"}},"type":"object","required":["email"],"title":"SingleReq"},"SuppressionAddReq":{"properties":{"email":{"type":"string","title":"Email"},"reason":{"type":"string","title":"Reason","default":"manual"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"expires_in_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires In Days"}},"type":"object","required":["email"],"title":"SuppressionAddReq"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}