Verify email

Evaluates an email address using explicitly selected, composable checks.

POST /v1/email/verify

Email → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/email/verify`
Method	`POST`
Operation	`post_email_verify`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Evaluates an email address using explicitly selected, composable checks.

A signed-in caller only: the SMTP check connects to the address's mail server from ours, so an anonymous caller could probe mailboxes and get our addresses blocked. Each caller may run 120 checks an hour and 20 of them SMTP probes, and the deployment 6,000 and 400; past either is 429.

POST /v1/email/verify

Request

6 fields, body application/json (required).

Field	In	Type	Required	Description
`checks`	body	string[]	—	Checks explicitly selects which checks to run.
`email`	body	string	—	Email is the address to evaluate.
`from_email`	body	string	—	FromEmail sets sender used in MAIL FROM for SMTP probe when explicitly enabled.
`hello_name`	body	string	—	HelloName sets domain used in EHLO for SMTP probe when explicitly enabled.
`proxy_uri`	body	string	—	ProxyURI sets optional proxy for network lookups.
`suggestions`	body	boolean	—	Suggestions requests domain typo suggestions without altering the original email.

Response

Status	Body	Meaning
`200`	email.VerificationResult	ok
`default`	problem-details	refused

200 body — 31 fields.

Field	In	Type	Always	Description
`checks`	body	email.VerificationChecks	—
`checks.classification`	body	email.ClassificationCheck	—
`checks.classification.disposable`	body	boolean	—	Disposable reports whether the domain belongs to a temporary or throwaway provider.
`checks.classification.free`	body	boolean	—	Free reports whether the domain belongs to a free consumer webmail provider.
`checks.classification.reason`	body	string	—	Reason describes the failure or skip reason when Status is not pass.
`checks.classification.role`	body	boolean	—	Role reports whether the address is a generic role or distribution account.
`checks.classification.status`	body	string	—	Status reports the check outcome: pass, fail, unknown, or skipped.
`checks.domain`	body	email.DomainCheck	—
`checks.domain.reason`	body	string	—	Reason describes the failure or skip reason when Status is not pass.
`checks.domain.status`	body	string	—	Status reports the check outcome: pass, fail, unknown, or skipped.
`checks.mx`	body	email.MXCheck	—
`checks.mx.reason`	body	string	—	Reason describes the failure or skip reason when Status is not pass.
`checks.mx.records`	body	string[]	—	Records lists the discovered mail exchanger hostnames.
`checks.mx.status`	body	string	—	Status reports the check outcome: pass, fail, unknown, or skipped.
`checks.smtp`	body	email.SMTPCheck	—
`checks.smtp.catch_all`	body	boolean	—	CatchAll reports whether the host accepts all recipient addresses.
`checks.smtp.deliverable`	body	boolean	—	Deliverable reports whether the mailbox accepted the test recipient address.
`checks.smtp.disabled`	body	boolean	—	Disabled reports whether the recipient mailbox is disabled or inactive.
`checks.smtp.full_inbox`	body	boolean	—	FullInbox reports whether the recipient mailbox is over quota.
`checks.smtp.host_exists`	body	boolean	—	HostExists reports whether the destination mail server host exists and responded.
`checks.smtp.reason`	body	string	—	Reason describes the failure or skip reason when Status is not pass.
`checks.smtp.status`	body	string	—	Status reports the check outcome: pass, fail, unknown, or skipped.
`checks.syntax`	body	email.SyntaxCheck	—
`checks.syntax.domain`	body	string	—	Domain is the domain-part of the email address.
`checks.syntax.reason`	body	string	—	Reason describes the failure or skip reason when Status is not pass.
`checks.syntax.status`	body	string	—	Status reports the check outcome: pass, fail, unknown, or skipped.
`checks.syntax.username`	body	string	—	Username is the local-part of the email address.
`email`	body	string	—	Email is the original submitted email address.
`suggestions`	body	email.Suggestion[]	—	Suggestions lists potential corrections when requested.
`suggestions[].email`	body	string	—	Email is the suggested alternative address.
`suggestions[].reason`	body	string	—	Reason describes why the suggestion was made (e.g. domain_typo).

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo email verify

.ts

.py

.go

.rs

.java

import { Configuration, EmailApi } from 'hanzoai';

const api = new EmailApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postEmailVerify({ checks: ["<checks>"], email: "<email>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import EmailApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = EmailApi(client).post_email_verify(checks=["<checks>"], email="<email>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.EmailAPI.PostEmailVerify(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, email_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = email_api::post_email_verify(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.EmailApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new EmailApi(client).postEmailVerify();

curl -X POST https://api.hanzo.ai/v1/email/verify \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "checks": [
         "<checks>"
       ],
       "email": "<email>"
     }'

MCP reaches email through the email tool, which names its 8 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_emails"
         }
       }
     }'

Email API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousList email NextCreate sendgrid