Documentation
Everything you need to call the isBusinessEmail API: quickstart, authentication, fields, reason codes, limits, errors and integration guides.
QuickstartMake your first isBusinessEmail API call in 30 seconds with curl, JavaScript or Python, then switch from test addresses to a real key.API referenceEvery endpoint and field, generated from the OpenAPI 3.1 spec.Try it liveNo key needed for the website checker.
Getting started
- IntroductionWhat the isBusinessEmail API answers, how a check works, and where to start: work vs personal email, disposable, relay, Google Workspace and Microsoft 365.
- QuickstartMake your first isBusinessEmail API call in 30 seconds with curl, JavaScript or Python, then switch from test addresses to a real key.
- AuthenticationSecret keys (ibe_live_) for servers, publishable keys (ibe_pub_) for browsers, key rotation, and automatic revocation of keys leaked on GitHub.
- Test addressesReserved test.isbusinessemail.com addresses return fixed results with no key and never count toward quotas. Use them in docs, CI and smoke tests.
API reference
- Check an email, domain or websiteGET and POST /v1/check: check one email address, domain or website URL, choose a policy, request deep enrichment, and read the full response.
- Batch checksPOST /v1/check/batch checks up to 100 emails, domains or website URLs in one request. Each item counts toward your quota. Limits, response and retry advice.
- Verify that a mailbox existsPOST /v1/verify: ask the domain's mail server whether an exact address exists (no email is sent), with catch-all detection, and read status, reason and confidence.
- Report a wrong verdictPOST /v1/feedback tells us a verdict was wrong. Reports are reviewed by people, weighted by reporter trust, and never applied automatically.
- Usage and healthGET /v1/usage returns your own quota and usage; GET /v1/health reports API status; /openapi.json is the machine-readable spec.
- Response fieldsEvery field in a /v1/check response: category, recommendation, confidence, flags, mail, workspace, integrations, reasons, degraded and more.
- Categories and policiesThe eight categories (business, personal, disposable, relay, education, government, invalid, unknown) and how the b2b, strict and lenient policies map them.
- Reason codesEvery reason code isBusinessEmail returns in reasons[]: syntax, list matches, MX fingerprints, SPF/DMARC/DKIM, Microsoft tenant, domain age and more.
- Rate limits and quotasHow quotas work: the free tier counts checks per day, paid plans per month with no daily limit. Per-second and in-flight limits, how batch and deep checks count, rate-limit headers, and how to handle 429 responses.
- ErrorsisBusinessEmail errors are RFC 9457 problem+json with a stable code. Every code, its HTTP status, what causes it, and how to handle it.
- Versioning and deprecationHow the isBusinessEmail API is versioned, which changes are non-breaking, and how deprecations are announced with Deprecation and Sunset headers.
Guides
- MCP server for AI assistantsConnect Claude, ChatGPT, Cursor, VS Code and other MCP clients to isBusinessEmail: server URL, OAuth sign-in, tools, example prompts and limits.
- Google Workspace and Microsoft 365 detectionHow isBusinessEmail detects Google Workspace and Microsoft 365, finds the Entra tenant ID and federation, and what the detection deliberately does not do.
- Block personal emails at signup (without losing good users)A practical pattern for B2B signup forms: inline work-email hints, typo suggestions with did_you_mean, server-side enforcement and failing open.
- Code examplesCopy-paste isBusinessEmail API examples in curl, JavaScript, Node.js, Python, PHP, Go, Ruby, Java and C#, with timeouts and fail-open handling.
- Privacy and data handlingWhat isBusinessEmail stores when you check an address (domain and an HMAC, never the full email), retention, EU hosting, processors and your obligations.
- Server-side integration (Node client)Use isBusinessEmail from a backend or a mail pipeline: the zero-dependency Node client with timeouts, retries, caching and fail-open checks.