{ "openapi": "3.1.0", "info": { "title": "Bulk Email Checker API", "description": "A low-latency RESTful API for real-time email address verification. Performs 17+ factor validation including RFC syntax checks, DNS/MX record verification, disposable email detection, spam trap screening, role account detection, catch-all server identification, anti-greylisting, and a full SMTP handshake to confirm mailbox existence. Returns rich MX enrichment data with every request. Credits are consumed only for passed and failed results; unknown results are free.\n\n**Rate Limits by Account Tier:**\n| Tier | Hourly Quota | Max Concurrent Threads |\n|---|---|---|\n| Standard (< 1M Credits) | 1,500 req/hr | 1 |\n| Volume Tier 1 (1M+ Credits) | 2,500 req/hr | 3 |\n| Volume Tier 2 (10M+ Credits) | 4,000 req/hr | 5 |\n\nFor unlimited throughput, see the [Unlimited API](https://bulkemailchecker.com/unlimited-email-verification-api-pricing/).", "version": "1.0.0", "contact": { "name": "Bulk Email Checker Support", "email": "support@bulkemailchecker.com", "url": "https://bulkemailchecker.com/api-docs/" }, "termsOfService": "https://bulkemailchecker.com/terms-of-service/", "license": { "name": "Proprietary", "url": "https://bulkemailchecker.com/terms-of-service/" } }, "externalDocs": { "description": "Full API Documentation", "url": "https://bulkemailchecker.com/api-docs/" }, "servers": [ { "url": "https://api.bulkemailchecker.com", "description": "Production API server" } ], "security": [ { "ApiKeyQuery": [] } ], "paths": { "/real-time/": { "get": { "operationId": "verifyEmailGet", "summary": "Verify a single email address", "description": "Validates a single email address in real-time via a GET request. Performs syntax validation, DNS/MX record checks, disposable detection, spam trap screening, role account detection, and a full SMTP handshake. Returns JSON by default; append `xml=true` for XML output. 1 credit is consumed per passed or failed result. Unknown results consume no credits.", "tags": ["Email Verification"], "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your unique API key. Obtain from your account dashboard at https://panel.bulkemailchecker.com/", "schema": { "type": "string", "example": "YOUR_API_KEY" } }, { "name": "email", "in": "query", "required": true, "description": "The email address to validate. Must be URL encoded.", "schema": { "type": "string", "format": "email", "example": "example%40gmail.com" } }, { "name": "xml", "in": "query", "required": false, "description": "Set to `true` to receive an XML response instead of the default JSON.", "schema": { "type": "string", "enum": ["true"], "example": "true" } }, { "name": "label", "in": "query", "required": false, "description": "Custom label for tracking purposes. Failed emails are tagged with this label in your blacklist. URL encode if necessary. Defaults to 'Real-time API'.", "schema": { "type": "string", "example": "Contact%20Form" } } ], "responses": { "200": { "description": "Successful verification response. The `status` field indicates the outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResponse" }, "examples": { "passed": { "summary": "Valid mailbox", "value": { "status": "passed", "event": "mailbox_exists", "details": "The address provided passed all tests.", "email": "example@gmail.com", "emailSuggested": "", "mailbox": "example", "domain": "gmail.com", "isComplainer": false, "isDisposable": false, "isFreeService": true, "isGibberish": false, "isOffensive": false, "isRoleAccount": false, "timestampUTC": "2026-01-22T04:52:08Z", "execution": "0.03", "creditsRemaining": 99, "hourlyQuotaRemaining": 2498, "mxEnrichment": { "mxIp": "142.250.102.27", "mxHostname": "alt4.gmail-smtp-in.l.google.com", "mxCity": "", "mxPostalCode": "", "mxState": "Texas", "mxStateISOCode": "TX", "mxCountry": "United States", "mxCountryISOCode": "US", "mxContinent": "North America", "mxContinentISOCode": "NA", "mxTimezone": "America/Chicago", "mxLatitude": "32.7797", "mxLongitude": "-96.8022", "mxIsp": "Google Servers", "mxIspOrganization": "Google Servers", "mxAsn": 15169, "mxAsnOrganization": "GOOGLE", "mxIps": ["142.250.102.27", "172.253.116.27"], "mxHostnames": ["alt4.gmail-smtp-in.l.google.com", "alt1.gmail-smtp-in.l.google.com"] } } }, "failed": { "summary": "Invalid mailbox", "value": { "status": "failed", "event": "mailbox_does_not_exist", "details": "The mailbox does not exist on the mail server.", "email": "noone@example.com", "emailSuggested": "", "mailbox": "noone", "domain": "example.com", "isComplainer": false, "isDisposable": false, "isFreeService": false, "isGibberish": false, "isOffensive": false, "isRoleAccount": false, "timestampUTC": "2026-01-22T04:52:08Z", "execution": "0.07", "creditsRemaining": 98, "hourlyQuotaRemaining": 2497, "mxEnrichment": { "mxIp": "93.184.216.34", "mxHostname": "mail.example.com", "mxCity": "", "mxPostalCode": "", "mxState": "", "mxStateISOCode": "", "mxCountry": "United States", "mxCountryISOCode": "US", "mxContinent": "North America", "mxContinentISOCode": "NA", "mxTimezone": "", "mxLatitude": "", "mxLongitude": "", "mxIsp": "IANA", "mxIspOrganization": "IANA", "mxAsn": 15133, "mxAsnOrganization": "MCI-COMM", "mxIps": ["93.184.216.34"], "mxHostnames": ["mail.example.com"] } } }, "unknown_catchall": { "summary": "Catch-all domain", "value": { "status": "unknown", "event": "is_catchall", "details": "Domain accepts all emails (catch-all configuration).", "email": "anyone@catchalldomain.com", "emailSuggested": "", "mailbox": "anyone", "domain": "catchalldomain.com", "isComplainer": false, "isDisposable": false, "isFreeService": false, "isGibberish": false, "isOffensive": false, "isRoleAccount": false, "timestampUTC": "2026-01-22T04:52:08Z", "execution": "0.51", "creditsRemaining": 99, "hourlyQuotaRemaining": 2497, "mxEnrichment": {} } } } } } }, "429": { "description": "Rate limit exceeded. You have exceeded your hourly quota or concurrent thread limit. Implement exponential back-off and retry after 1-2 seconds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Rate limit exceeded" } } } } } } } }, "post": { "operationId": "verifyEmailPost", "summary": "Verify a single email address (POST)", "description": "Identical to the GET endpoint but accepts parameters via POST body with `application/x-www-form-urlencoded` content type. Useful when email addresses contain special characters or when GET query string length limits are a concern.", "tags": ["Email Verification"], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": ["key", "email"], "properties": { "key": { "type": "string", "description": "Your unique API key.", "example": "YOUR_API_KEY" }, "email": { "type": "string", "description": "The email address to validate. URL encoded.", "example": "example@gmail.com" }, "xml": { "type": "string", "description": "Set to `true` to receive XML response.", "enum": ["true"], "example": "true" }, "label": { "type": "string", "description": "Custom label for tracking failed addresses in your blacklist.", "example": "Contact Form" } } } } } }, "responses": { "200": { "description": "Successful verification response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResponse" } } } }, "429": { "description": "Rate limit exceeded." } } } } }, "components": { "securitySchemes": { "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "key", "description": "Your unique API key passed as a query parameter. Obtain from your account dashboard at https://panel.bulkemailchecker.com/" } }, "schemas": { "VerificationResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": ["passed", "failed", "unknown"], "description": "The top-level result of the verification. `passed` = valid deliverable address. `failed` = invalid address (1 credit consumed). `unknown` = result could not be determined (0 credits consumed).", "example": "passed" }, "event": { "type": "string", "enum": [ "mailbox_exists", "mailbox_does_not_exist", "mailbox_full", "invalid_syntax", "domain_does_not_exist", "mxserver_does_not_exist", "blacklisted_external", "blacklisted_failed", "blacklisted_domain", "is_catchall", "is_greylisting", "inconclusive" ], "description": "Detailed event code explaining the verification outcome.", "example": "mailbox_exists" }, "details": { "type": "string", "description": "Human-readable description of the validation result.", "example": "The address provided passed all tests." }, "email": { "type": "string", "description": "The email address that was validated.", "example": "example@gmail.com" }, "emailSuggested": { "type": "string", "description": "Suggested correction if a typo was detected (e.g., gnail.com -> gmail.com). Empty string if no suggestion.", "example": "" }, "mailbox": { "type": "string", "description": "The local part of the email address (before @).", "example": "example" }, "domain": { "type": "string", "description": "The domain part of the email address (after @).", "example": "gmail.com" }, "isComplainer": { "type": "boolean", "description": "True if the address is known to frequently report emails as spam.", "example": false }, "isDisposable": { "type": "boolean", "description": "True if the address uses a disposable or temporary email service (e.g., Mailinator, 10MinuteMail).", "example": false }, "isFreeService": { "type": "boolean", "description": "True if the address is from a free email provider (e.g., Gmail, Yahoo, Outlook).", "example": true }, "isGibberish": { "type": "boolean", "description": "True if the local part of the email appears to be random or meaningless characters.", "example": false }, "isOffensive": { "type": "boolean", "description": "True if the address contains offensive or inappropriate words.", "example": false }, "isRoleAccount": { "type": "boolean", "description": "True if the address is a role account (e.g., info@, admin@, support@, sales@).", "example": false }, "timestampUTC": { "type": "string", "format": "date-time", "description": "UTC timestamp of when the validation occurred (ISO 8601 format).", "example": "2026-01-22T04:52:08Z" }, "execution": { "type": "string", "description": "Time taken to validate the address in seconds.", "example": "0.03" }, "creditsRemaining": { "type": "integer", "description": "Number of verification credits remaining in your account.", "example": 99 }, "hourlyQuotaRemaining": { "type": "integer", "description": "Number of API requests remaining in your current hourly window.", "example": 2498 }, "mxEnrichment": { "$ref": "#/components/schemas/MxEnrichment" } } }, "MxEnrichment": { "type": "object", "description": "Detailed information about the recipient's mail server. Included free with every verification response.", "properties": { "mxIp": { "type": "string", "description": "Primary MX server IP address.", "example": "142.250.102.27" }, "mxHostname": { "type": "string", "description": "Primary MX server hostname.", "example": "alt4.gmail-smtp-in.l.google.com" }, "mxCity": { "type": "string", "description": "City where the MX server is located (if available).", "example": "Mountain View" }, "mxPostalCode": { "type": "string", "description": "Postal code of the MX server location (if available).", "example": "94039" }, "mxState": { "type": "string", "description": "State or region where the MX server is located.", "example": "Texas" }, "mxStateISOCode": { "type": "string", "description": "ISO 3166-2 state/region code (e.g., TX for Texas).", "example": "TX" }, "mxCountry": { "type": "string", "description": "Country where the MX server is located.", "example": "United States" }, "mxCountryISOCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "mxContinent": { "type": "string", "description": "Continent where the MX server is located.", "example": "North America" }, "mxContinentISOCode": { "type": "string", "description": "Continent code (NA, EU, AS, AF, OC, SA, AN).", "example": "NA" }, "mxTimezone": { "type": "string", "description": "IANA timezone of the MX server location.", "example": "America/Chicago" }, "mxLatitude": { "type": "string", "description": "Latitude coordinate of the MX server.", "example": "32.7797" }, "mxLongitude": { "type": "string", "description": "Longitude coordinate of the MX server.", "example": "-96.8022" }, "mxIsp": { "type": "string", "description": "Internet Service Provider hosting the MX server.", "example": "Google Servers" }, "mxIspOrganization": { "type": "string", "description": "Organization name of the ISP.", "example": "Google Servers" }, "mxAsn": { "type": "integer", "description": "Autonomous System Number of the MX server's network.", "example": 15169 }, "mxAsnOrganization": { "type": "string", "description": "Organization name associated with the ASN.", "example": "GOOGLE" }, "mxIps": { "type": "array", "items": { "type": "string" }, "description": "All MX server IP addresses for the domain.", "example": ["142.250.102.27", "172.253.116.27", "142.251.16.27"] }, "mxHostnames": { "type": "array", "items": { "type": "string" }, "description": "All MX server hostnames for the domain, ordered by priority.", "example": ["alt4.gmail-smtp-in.l.google.com", "alt1.gmail-smtp-in.l.google.com", "gmail-smtp-in.l.google.com"] } } } } }, "tags": [ { "name": "Email Verification", "description": "Real-time SMTP-based email address validation endpoints." } ] }