Verify

Verify an email address

Synchronously check whether one email address is deliverable. The reachability verdict is the headline outcome: safe (the mailbox was positively confirmed — requires an external escalation, so rarely returned today), risky (routable but low quality, such as a spam-listed domain or a role/shared inbox), invalid (undeliverable: bad syntax, no mail server, a disposable domain, or an address that hard-bounced on a real send before), or unknown (deliverable-looking but not confirmed without sending, the common default). It also returns a 0–100 score, a stable reasonCode twinned with the prose reason, a suggestedCorrection for likely typos, and the syntax/mx/signals evidence. The result is computed per request: it is not stored and has no id.

POST

verify

import { createClient } from "@norbelys/sdk";

const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY });

const { data, error } = await norbelys.verify.email({ email: "[email protected]" });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "checkedAt": "2026-07-04T09:00:00.000Z",
  "email": "[email protected]",
  "mx": {
    "acceptsMail": true,
    "provider": "google",
    "records": [
      "aspmx.l.google.com"
    ]
  },
  "reachability": "unknown",
  "reason": "Deliverable format on a domain that accepts mail (hosted on google).",
  "reasonCode": "deliverable_unconfirmed",
  "score": 88,
  "signals": {
    "isDisposable": true,
    "isFreeEmail": true,
    "isGibberish": true,
    "isReputable": true,
    "isRoleAccount": true,
    "isSpamDomain": true
  },
  "suggestedCorrection": "[email protected]",
  "syntax": {
    "domain": "acme.com",
    "isValidSyntax": true,
    "localPart": "ada"
  },
  "object": "email_verification"
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Org-scoped Norbelys API key. Create one in Settings → API keys and send it as Authorization: Bearer ak_….

Headers

Idempotency-Key

string

Opt-in idempotency for a safely retried write: reuse the same key to replay the original result for 24h instead of re-executing. Recommended on every POST.

Maximum string length: 255

Body

application/json

The request body for a synchronous email verification: one address to check.

string

required

The email address to verify.

Required string length: 1 - 320

Example:

"[email protected]"

Response

A synchronous email-verification result: the reachability rollup with score/reason/reasonCode, plus the syntax/mx/signals evidence. Computed per request — it is not stored and has no id.

checkedAt

string<date-time>

required

When this verdict was computed (RFC 3339). Verdicts are cached for 24h, so this can be up to a day old.

Example:

"2026-07-04T09:00:00.000Z"

string

required

The normalized (trimmed, lowercased) address that was checked.

Example:

"[email protected]"

VerifyMx · object

required

DNS / mail-exchanger checks.

Show child attributes

reachability

enum<string>

required

The single deliverability verdict. "safe" = the mailbox was positively confirmed (rarely returned); "risky" = routable but low quality — a spam-listed domain, a role/shared inbox, or an accept-all domain; "invalid" = undeliverable — bad syntax, an unregistrable TLD, a disposable domain, no mail server, or a previously bounced address; "unknown" = a deliverable-looking address whose mailbox could not be confirmed without sending (the common default).

Available options:

safe,

risky,

invalid,

unknown

Example:

"unknown"

reason

string

required

A short, human-readable explanation of the verdict.

Example:

"Deliverable format on a domain that accepts mail (hosted on google)."

reasonCode

enum<string>

required

Stable machine-readable code for the dominant reason (the companion to the prose reason). Values: invalid_syntax (not a valid address format) · typo_suspected (a likely correction exists — see suggestedCorrection) · invalid_tld (the domain suffix is not a registrable IANA/public-suffix entry) · disposable (throwaway / temp-mail domain) · no_mail_server (the domain has no MX) · previously_bounced (a real send to this address hard-bounced before — it WILL bounce again) · spam_listed (the domain is on a spam/abuse blocklist) · undeliverable (an external check rejected the mailbox) · accept_all (the domain accepts mail for any local part) · risky_tld (on a frequently-abused TLD and not reputable) · gibberish_local (the local part looks random) · role_account (a role / shared inbox like info@ or sales@) · deliverable (an external check confirmed the mailbox) · deliverable_unconfirmed (deliverable format on a domain that accepts mail, mailbox not confirmed).

Available options:

invalid_syntax,

typo_suspected,

invalid_tld,

disposable,

no_mail_server,

previously_bounced,

spam_listed,

undeliverable,

accept_all,

risky_tld,

gibberish_local,

role_account,

deliverable,

deliverable_unconfirmed

Example:

"deliverable_unconfirmed"

score

integer

required

Quality and confidence score from 0 to 100; higher means more likely a real, deliverable address.

Required range: 0 <= x <= 100

Example:

88

signals

VerifySignals · object

required

The individual quality signals behind the verdict.

Show child attributes

suggestedCorrection

string | null

required

A suggested correction when the address looks like a typo, or null.

Example:

"[email protected]"

syntax

VerifySyntax · object

required

Syntax checks.

Show child attributes

object

any

default:email_verification

Always "email_verification" — identifies the resource type.

import { createClient } from "@norbelys/sdk";

const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY });

const { data, error } = await norbelys.verify.email({ email: "[email protected]" });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "checkedAt": "2026-07-04T09:00:00.000Z",
  "email": "[email protected]",
  "mx": {
    "acceptsMail": true,
    "provider": "google",
    "records": [
      "aspmx.l.google.com"
    ]
  },
  "reachability": "unknown",
  "reason": "Deliverable format on a domain that accepts mail (hosted on google).",
  "reasonCode": "deliverable_unconfirmed",
  "score": 88,
  "signals": {
    "isDisposable": true,
    "isFreeEmail": true,
    "isGibberish": true,
    "isReputable": true,
    "isRoleAccount": true,
    "isSpamDomain": true
  },
  "suggestedCorrection": "[email protected]",
  "syntax": {
    "domain": "acme.com",
    "isValidSyntax": true,
    "localPart": "ada"
  },
  "object": "email_verification"
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

Analytics

Domains

Fields

Files

Groups

Integrations

Messages

Organization

People

Programs

Segments

Senders

Suppressions

Verify

Verify an email address

Authorizations

Headers

Body

Response