Bulk Email Validation Response

Utilities
POST /api/v1/email/validate/bulk Bearer

A successful Bulk Email Validation call returns success: true and the verification result under data.result.

Success Response — 200

{
    "status": "SUCCESS",
    "status_code": 200,
    "charged": true,
    "success": true,
    "message": "",
    "message_code": "OK",
    "order_id": "W2A1739512345abcdef01",
    "data": {
        "order_id": "W2A1739512345abcdef01",
        "result": {
            "total_requested": 3,
            "total_returned": 3,
            "results": [
                {
                    "email": "[email protected]",
                    "result": "valid",
                    "is_valid": true,
                    "is_syntax_valid": true,
                    "reason": "",
                    "domain": {
                        "name": "example.com",
                        "is_valid": true,
                        "is_disposable": false,
                        "is_free": false,
                        "is_spam": false,
                        "is_catch_all": false
                    },
                    "account": {
                        "is_role": false,
                        "is_full_mailbox": false
                    },
                    "mx_records": [
                        "mx1.example.com.",
                        "mx2.example.com.",
                        "mx3.example.com.",
                        "mx4.example.com.",
                        "mx5.example.com."
                    ]
                },
                {
                    "email": "not-an-email",
                    "result": "invalid_syntax",
                    "is_valid": false,
                    "is_syntax_valid": false,
                    "reason": "",
                    "domain": {
                        "name": "not-an-email",
                        "is_valid": false,
                        "is_disposable": false,
                        "is_free": false,
                        "is_spam": false,
                        "is_catch_all": false
                    },
                    "account": {
                        "is_role": false,
                        "is_full_mailbox": false
                    },
                    "mx_records": []
                },
                {
                    "email": "[email protected]",
                    "result": "invalid",
                    "is_valid": false,
                    "is_syntax_valid": true,
                    "reason": "mx record does not exist.",
                    "domain": {
                        "name": "nonexistentdomainxyz123abc.com",
                        "is_valid": false,
                        "is_disposable": false,
                        "is_free": false,
                        "is_spam": false,
                        "is_catch_all": false
                    },
                    "account": {
                        "is_role": false,
                        "is_full_mailbox": false
                    },
                    "mx_records": []
                }
            ]
        }
    }
}

Response Keys

Key Type What it tells you
status string Order lifecycle: SUCCESS, PENDING or FAILED. Describes the order, not the verification — a charged call that came back negative is a completed order.
status_code int The HTTP status, echoed into the body.
charged bool The authority on billing. Never infer it from the HTTP status.
success bool The verification outcome. Independent of charged.
message string Human-readable text. For display and logs — do not parse it.
message_code string Machine-readable reason from a fixed vocabulary. Branch on this.
order_id string Present once a call reached the provider; quote it on a support ticket. Its absence means nothing was billed.
data.result object The verification payload for this endpoint.

When You Are Charged

message_code Charged HTTP status What it means
OK Yes 200 SUCCESS Verified. The provider ran the lookup and returned a result.
ACCEPTED Yes 202 PENDING Queued at the provider. Quote the order_id to collect the result.
PROVIDER_NO_RESPONSE Yes 202 PENDING The provider did not respond in time. Held for manual review — not auto-refunded.
VERIFICATION_FAILED Yes 422 SUCCESS The provider ran the lookup and the details did not verify. The work was done, so the call is billed.
NO_RECORD_FOUND Yes 422 SUCCESS The provider ran the lookup and found no matching record. Billed for the same reason.
INVALID_INPUT No 422 FAILED Your parameters were rejected before any call was placed.
REQUEST_FAILED No 400 FAILED The call was placed and failed definitively. Refunded to your wallet automatically.
MISSING_API_KEY No 401 FAILED No API key on the request.
INVALID_API_KEY No 401 FAILED Key invalid or expired, or the calling IP is not allowed.
INSUFFICIENT_BALANCE No 402 FAILED Your wallet balance is below the price of this call.
NO_API_ACCESS No 403 FAILED Your account is not subscribed to this API.
NOT_FOUND No 404 FAILED No such endpoint.
RATE_LIMITED No 429 FAILED Per-key, per-service one-minute limit exceeded.
INTERNAL_ERROR No 500 FAILED Unexpected error on our side.
PROVIDER_UNAVAILABLE No 503 FAILED The service could not be reached.