Verify a single email address in real time, understand every response field, and check your remaining credits — all with simple GET requests.
token parameter
1 credit per verification
Every request is authenticated with your personal API key, passed as the
token query parameter. You can find your API key in your
ValidEmail dashboard after signing in.
Keep your key secret. Call the API from your backend and never embed the key in client-side code, public repositories, or mobile apps.
Runs the full verification pipeline — syntax, domain and MX checks, disposable and role detection, and a live mailbox check — and responds in real time. Each verification consumes one credit.
| Parameter | Required | Description |
|---|---|---|
email | Yes | The email address to verify. |
token | Yes | Your API key. |
{
"IsValid": true,
"Score": 95,
"Email": "validemailnet@gmail.com",
"State": "Deliverable",
"Reason": "ACCEPTED EMAIL",
"Domain": "gmail.com",
"Free": true,
"Role": false,
"Disposable": false,
"AcceptAll": false,
"Tag": false,
"MXRecord": "gmail-smtp-in.l.google.com.",
"RetryAfterSeconds": null,
"EmailAdditionalInfo": []
}{
"IsValid": false,
"Score": 0,
"Email": "someone@greylisting-domain.com",
"State": "Unknown",
"Reason": "GREYLISTED",
"Domain": "greylisting-domain.com",
"Free": false,
"Role": false,
"Disposable": false,
"AcceptAll": false,
"Tag": false,
"MXRecord": "mx1.greylisting-domain.com",
"RetryAfterSeconds": 60,
"EmailAdditionalInfo": []
}State = "Unknown")
Some mail servers greylist first-time senders or respond slowly. Instead of failing, the API returns an
interim 200 OK result with State = "Unknown", a Reason of
PENDING or GREYLISTED, and a RetryAfterSeconds hint while the
verification finishes in the background.
RetryAfterSeconds seconds, then repeat the same request to get the final verdict.Unknown as "not yet decided" — never as a delivery failure.| Field | Type | Description |
|---|---|---|
IsValid | boolean | true when the address passed verification and is safe to send to. |
Score | integer (0–100) | Deliverability confidence score. We recommend sending only to 80+. |
Email | string | The queried address, normalized to lower case. |
State | string | Deliverable, Not Deliverable, or Unknown (interim — retry later). |
Reason | string | Why the state was assigned — see the reason table below. |
Domain | string | Domain part of the address (e.g. gmail.com). |
Free | boolean | true for free providers such as Gmail, Yahoo, or Outlook.com. |
Role | boolean | true for role inboxes such as info@, support@, admin@. |
Disposable | boolean | true for temporary / throw-away providers. |
AcceptAll | boolean | true when the domain accepts any recipient — treat positives with caution. |
Tag | boolean | true when the address contains a plus-tag (e.g. user+tag@domain.com). |
MXRecord | string | Mail exchange host that answers for the domain. |
RetryAfterSeconds | integer or null | Present only on Unknown interim results: how long to wait before re-querying. null on definitive results. |
EmailAdditionalInfo | array | Optional list of { Key, Value } pairs with extra diagnostic details. |
| State | Typical reasons | Meaning |
|---|---|---|
| Deliverable | ACCEPTED EMAIL |
The mailbox exists and accepts mail. |
| Not Deliverable | REJECTED EMAIL, INVALID DOMAIN |
The mailbox or its domain rejected the address. Do not send. |
| Unknown | PENDING, GREYLISTED, VERIFICATION TIMEOUT |
No final verdict yet. When RetryAfterSeconds is set, retry the same request after that delay. |
Returns the number of verification credits you have left. This call is free — it never consumes a credit — and is ideal for dashboards or pre-flight checks before large sends.
{
"balance": 12450
}Your balance is also always visible in your ValidEmail dashboard.
| HTTP Status | Meaning | What to do |
|---|---|---|
| 200 OK | The request was processed. Check State — a result with State = "Unknown" and a RetryAfterSeconds value is an interim answer, not a final verdict. |
Use the result. If State is Unknown, retry the same request after RetryAfterSeconds. |
| 400 Bad Request | Missing email/token parameter, no credits remaining, or a transient processing failure. |
Check the response text. If you are out of credits, top up your balance before retrying. |
| 401 Unauthorized | The API key is invalid or unknown. | Verify the token value against the API key shown in your dashboard. |
| 403 Forbidden | The account attached to this API key is inactive. | Contact info@validemail.net to reactivate the account. |
| 429 Too Many Requests | You exceeded your per-second request limit. The response body includes the configured limit. | Slow down and retry with backoff, or contact us to raise your rate limit. |
IsValid = true and Score ≥ 80.State = "Unknown", retry after RetryAfterSeconds instead of discarding the address.Disposable addresses to protect your sender reputation.Role inboxes for marketing campaigns.AcceptAll domains with caution — the server accepts every recipient, so a positive result is weaker evidence./balance and top up before large campaigns; requests fail with 400 when you run out of credits.Step-by-step tutorials with complete, copy-paste code.