Skip to main content
MailInsightX Developers

Getting Started

API Reference

Changelog

Last updated September 17, 2026

POST /v1/verify

Verifies a single email address, including real-time enhanced verification. This is the only API operation that spends credits.

Warning

There is no webhook/callback and no batch endpoint - this is a synchronous, single-email-per-request API. For multiple addresses, make multiple requests, respecting the rate limit.

Request

POST /v1/verify HTTP/1.1
Host: mailinsightx.com
x-api-key: mi_your_api_key
Content-Type: application/json
 
{ "email": "[email protected]" }
Field Type Required Notes
email string Yes Must be a valid email format, 255 characters or fewer.

Credits

This endpoint always spends 1 InsightX+ credit per call, regardless of the result - unlike some Standard-only checks elsewhere in the product. A few definitive results (Disposable, Parked (Risky), Invalid Domain (No MX)) are answered without ever needing a live SMTP check, but still charge the credit, since you're paying for a definitive answer either way. If the request fails before any answer is produced at all (worker unavailable/unreachable, an internal error), the credit is automatically refunded - see the error table below for exactly which cases refund.

Response

{
  "email": "[email protected]",
  "result": {
    "status": "Valid",
    "mx_valid": true,
    "smtp_valid": true,
    "is_catch_all": false,
    "is_role_account": false,
    "is_disposable": false,
    "is_gibberish": false
  }
}

is_role_account, is_disposable, and is_gibberish reflect the real, live-checked result for the address you sent - not fixed placeholder values.

result.status is one of: Valid, Catch-All (Risky), Hard Bounce (SMTP), Mailbox Full (Temporary), Greylisted (Temporary), Tarpitted (Risky), Unverified (Port Blocked), Disposable, Parked (Risky), Invalid Domain (No MX), Role-Based (Risky), Gibberish (Risky). See the Verification Status Glossary for what each one means.

Tip

The raw SMTP conversation transcript is intentionally never included in this response, for security reasons - only the derived fields above.

Errors

Status Body Credit refunded?
400 { "error": "<validation message>" } (e.g. invalid email format) N/A - never charged
402 { "error": "Insufficient InsightX+ credits" } N/A - never charged
500 { "error": "Failed to verify email" } (verification backend unavailable) Yes
500 { "error": "Internal server error" } Yes, if a credit had already been deducted
502 { "error": "Failed to verify email" } (verification backend unreachable after retries) Yes

Also see the common authentication and rate-limit errors.