Verification API documentation

Overview

Send a JSON request containing one email address. A successful request returns HTTP 200. Quick costs 0.5 credit, standard costs 1 credit, and deepcheck costs 2 credits. Unknown results are free.

POST

https://api.mailtooth.com/verify/single

Authentication

Every request must include an active API key in the x-api-key header. Create and copy keys from the API keys page in your dashboard. Keep keys server-side and never expose them in browser code or public repositories.

Headerx-api-key: YOUR_API_KEY

Request

Use Content-Type: application/json and provide the email to verify in the request body.

Field	Type	Required	Description
`email`	string	Yes	A syntactically valid email address.
`type`	string	No	quick, standard, or deepcheck. The deprecated enriched and pro aliases map to deepcheck. Defaults to standard.

cURL request

curl --request POST 'https://api.mailtooth.com/verify/single' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{"email":"hello@example.com","type":"standard"}'

Verification types

Choose the least expensive type that provides the evidence your workflow needs. standard is the default; use deepcheck when you need an individual mailbox verdict.

Type	Best for	Response depth	Cost
`quick`	Fast list hygiene and domain-level screening. It does not contact the mailbox.	Compact status and base-check results; score is omitted.	0.5 credit
`standard`	Domain intelligence, security posture, and routine list cleaning.	Baseline results plus ESP, parking, authentication, DNSBL, and WHOIS evidence.	1 credit
`deepcheck`	Mailbox deliverability, catch-all detection, and deep due diligence.	Complete domain intelligence plus SMTP mailbox and catch-all evidence.	2 credits

enriched and pro remain accepted as deprecated request aliases. Responses always report deepcheck in verificationType.

Checks performed

Check	What it answers	Quick	Standard	Deepcheck
Syntax validation	Validates the address structure before any network checks.	Included	Included	Included
DNS / MX records	Confirms that the domain exists and publishes usable mail exchangers.	Included	Included	Full records
Disposable email	Detects known temporary and throwaway email providers.	Included	Included	Included
Role-based address	Detects shared functional inboxes such as admin, billing, sales, support, and no-reply.	Category	Adds confidence	Adds signals
Personal / professional	Classifies the address using provider and validated-domain evidence.	Category	Adds confidence	Adds evidence
TLD domain risk	Evaluates reputation risk associated with the registered domain and TLD.	Summary	Summary	Adds signals
Name extraction	Parses person-like mailbox names such as john.doe.	Public fields	Public fields	Adds derivation
ESP / infrastructure detection	Identifies mailbox hosts, gateways, forwarding services, and providers from MX evidence.	—	Summary	Full hosts + priorities
Parked / inactive domain	Detects parked pages, redirects, and related inactive-domain indicators.	—	Summary	Full evidence
SPF, DKIM, and DMARC	Assesses sender-authentication configuration and associated risk.	—	Summary	Full records
DNSBL / RBL blocklists	Checks the domain and mail infrastructure for reputation listings.	—	Summary	Full listings
WHOIS / domain age	Evaluates registration, domain age, expiry, and ownership-risk evidence.	—	Summary	Full evidence
SMTP mailbox existence	Connects to the receiving mail server and tests the individual mailbox.	Not checked	Not checked	Included
SMTP catch-all detection	Determines whether the server accepts mail for arbitrary recipients.	Not checked	Not checked	Included

Quick is intentionally domain-levelWhen syntax, domain, and MX checks pass, Quick and Standard return addressStatus: "valid" and mailbox.status: "not_checked". The mailbox signal tells customers to run Deepcheck when they need a mailbox-level verdict. Standard adds domain, reputation, and sender-security intelligence without contacting the mailbox.

Verification statuses

Address validation and mailbox deliverability are separate decisions. Use addressStatus for syntax, domain, and MX handling. Use mailbox.status only when mailbox-level routing matters.

valid

Syntax, domain, and MX checks passed. This does not claim that the mailbox exists.

invalid

A conclusive address-level check failed, such as syntax, domain, or MX.

not_checked

The selected tier intentionally did not perform a mailbox check.

unknown

An attempted required check did not return a conclusive result. No credit is charged.

Result	Meaning	Handling
`addressStatus: valid`	The address-level checks passed.	Accept at domain level; use Deepcheck for mailbox confirmation.
`addressStatus: invalid`	A conclusive address check failed.	Reject or request a correction.
`mailbox: not_checked`	Mailbox verification was intentionally excluded or skipped.	Follow the structured signal action when confirmation is required.
`mailbox: deliverable / risky / undeliverable`	Deepcheck obtained mailbox-level evidence.	Accept, review, or reject according to the mailbox result.
`unknown`	An attempted required check could not answer.	Retry later; the request is refunded.

Responses by verification type

Every successful request returns HTTP 200, but its JSON shape is intentionally tier-specific. Do not assume fields from a deeper type exist in a shallower response.

Role-based detection is included in every type. It identifies a shared or functional recipient; it does not make a deliverable mailbox undeliverable or reduce its deliverability score.

Person enrichment is also included in every type for person-like mailbox names. Quick and standard both return every public person result field, including name and gender confidence plus directional probability when available. Gender values are statistical associations between first names and reference-dataset labels—not a statement of a recipient's identity. Role mailboxes are not evaluated as people.

Email-provider detection is included in standard and deepcheck. Security gateways and forwarding services report an unknown routing category because their MX records hide the downstream mailbox provider.

Quick response

Compact domain-level evidence. SMTP and extended domain intelligence are omitted.

Quick · HTTP 200

{
  "email": "priya.sharma@gmail.com",
  "verificationType": "quick",
  "addressStatus": "valid",
  "mailbox": {
    "status": "not_checked",
    "signals": [
      {
        "code": "mailbox_check_not_included",
        "severity": "info",
        "message": "Run Deepcheck to verify mailbox deliverability.",
        "action": "run_deepcheck"
      }
    ]
  },
  "risk": {
    "level": "low",
    "signals": []
  },
  "signals": [],
  "details": {
    "syntax": {
      "status": "valid"
    },
    "domain": {
      "status": "valid"
    },
    "mx": {
      "status": "valid"
    },
    "disposable": {
      "status": "not_detected"
    },
    "roleBased": {
      "status": "not_detected",
      "category": "unknown"
    },
    "person": {
      "status": "detected",
      "firstName": "Priya",
      "lastName": "Sharma",
      "nameConfidence": "high",
      "gender": "female",
      "genderConfidence": "high",
      "genderProbability": 0.98
    },
    "emailClassification": {
      "category": "personal"
    },
    "tldDomainRisk": {
      "tld": "com",
      "registeredDomain": "gmail.com",
      "category": "standard",
      "riskLevel": "low"
    }
  },
  "creditsCharged": 0.5,
  "creditsRemaining": 499.5,
  "meta": {
    "modelVersion": "deliverability-v2"
  }
}

Standard response

Adds ESP detection, parking, sender authentication, DNSBL, and WHOIS intelligence. It does not perform SMTP mailbox or catch-all probes.

Standard · HTTP 200

{
  "email": "priya.sharma@gmail.com",
  "verificationType": "standard",
  "addressStatus": "valid",
  "mailbox": {
    "status": "not_checked",
    "signals": [
      {
        "code": "mailbox_check_not_included",
        "severity": "info",
        "message": "Run Deepcheck to verify mailbox deliverability.",
        "action": "run_deepcheck"
      }
    ]
  },
  "risk": {
    "level": "low",
    "signals": []
  },
  "signals": [],
  "details": {
    "syntax": {
      "status": "valid"
    },
    "domain": {
      "status": "valid"
    },
    "mx": {
      "status": "valid"
    },
    "disposable": {
      "status": "not_detected"
    },
    "roleBased": {
      "status": "not_detected",
      "category": "unknown",
      "confidence": "high"
    },
    "person": {
      "status": "detected",
      "firstName": "Priya",
      "lastName": "Sharma",
      "nameConfidence": "high",
      "gender": "female",
      "genderConfidence": "high",
      "genderProbability": 0.98
    },
    "emailClassification": {
      "category": "personal",
      "confidence": "high",
      "provider": "Gmail"
    },
    "tldDomainRisk": {
      "tld": "com",
      "registeredDomain": "gmail.com",
      "category": "standard",
      "riskLevel": "low"
    },
    "emailProvider": {
      "status": "detected",
      "providerId": "google_workspace",
      "provider": "Google Workspace",
      "infrastructureType": "cloud_mailbox",
      "routingCategory": "google",
      "confidence": "high",
      "hasSecondaryProvider": false,
      "hasUnrecognizedMx": false
    },
    "parking": {
      "status": "active",
      "isRedirected": false,
      "riskLevel": "low"
    },
    "emailAuthentication": {
      "spf": {
        "status": "pass"
      },
      "dkim": {
        "status": "pass"
      },
      "dmarc": {
        "status": "pass",
        "policy": "reject"
      },
      "riskLevel": "low"
    },
    "dnsbl": {
      "status": "clear",
      "checks": {
        "total": 40,
        "listed": 0,
        "failed": 0
      },
      "riskLevel": "low"
    },
    "whois": {
      "status": "registered",
      "createdAt": "1995-08-14T00:00:00Z",
      "expiresAt": "2027-08-13T00:00:00Z",
      "domainAgeDays": 11320,
      "riskLevel": "low"
    }
  },
  "creditsCharged": 1,
  "creditsRemaining": 499,
  "meta": {
    "modelVersion": "deliverability-v2"
  }
}

Deepcheck response

Adds SMTP mailbox and catch-all results, one deliverability score and confidence, and complete customer-relevant evidence. Internal scoring dimensions, factor weights, contributions, and coverage are never exposed.

Deepcheck · HTTP 200

{
  "email": "priya.sharma@company.com",
  "verificationType": "deepcheck",
  "addressStatus": "valid",
  "mailbox": {
    "status": "deliverable",
    "isCatchAll": false,
    "reason": "mailbox_confirmed",
    "signals": [
      {
        "code": "smtp_mailbox_confirmed",
        "severity": "positive",
        "message": "The receiving server accepted this mailbox."
      }
    ],
    "evidence": {
      "responseCode": 250,
      "enhancedStatusCode": "2.1.5",
      "mxHost": "mx.company.com",
      "attemptedMxHosts": [
        "mx.company.com"
      ]
    }
  },
  "risk": {
    "level": "low",
    "signals": []
  },
  "score": 94,
  "confidence": "high",
  "signals": [],
  "details": {
    "syntax": {
      "status": "valid"
    },
    "domain": {
      "status": "valid"
    },
    "mx": {
      "status": "valid",
      "records": [
        {
          "host": "mx.company.com",
          "priority": 10,
          "isPrimary": true
        }
      ]
    },
    "disposable": {
      "status": "not_detected"
    },
    "roleBased": {
      "status": "not_detected",
      "category": "unknown",
      "confidence": "high"
    },
    "person": {
      "status": "detected",
      "firstName": "Priya",
      "lastName": "Sharma",
      "nameConfidence": "high",
      "gender": "female",
      "genderConfidence": "high",
      "genderProbability": 0.98,
      "derivedFrom": "local_part",
      "signals": []
    },
    "emailClassification": {
      "category": "personal",
      "confidence": "high",
      "provider": "Gmail"
    },
    "tldDomainRisk": {
      "tld": "com",
      "registeredDomain": "gmail.com",
      "category": "standard",
      "riskLevel": "low"
    },
    "emailProvider": {
      "status": "detected",
      "providerId": "google_workspace",
      "provider": "Google Workspace",
      "infrastructureType": "cloud_mailbox",
      "routingCategory": "google",
      "confidence": "high",
      "hasSecondaryProvider": false,
      "hasUnrecognizedMx": false,
      "primaryProvider": {
        "id": "google_workspace",
        "name": "Google Workspace",
        "infrastructureType": "cloud_mailbox",
        "routingCategory": "google"
      },
      "observedProviders": [
        {
          "id": "google_workspace",
          "name": "Google Workspace",
          "infrastructureType": "cloud_mailbox",
          "routingCategory": "google",
          "isPrimary": true,
          "mxRecords": [
            {
              "host": "mx.company.com",
              "priority": 10,
              "isPrimary": true
            }
          ]
        }
      ],
      "mxRecords": [
        {
          "host": "mx.company.com",
          "priority": 10,
          "isPrimary": true
        }
      ],
      "signals": []
    },
    "parking": {
      "status": "active",
      "isRedirected": false,
      "riskLevel": "low",
      "finalUrl": "https://company.com",
      "redirectChain": [],
      "indicators": [],
      "signals": []
    },
    "emailAuthentication": {
      "spf": {
        "status": "pass",
        "record": "v=spf1 include:_spf.google.com -all",
        "mechanisms": [
          "include:_spf.google.com",
          "-all"
        ],
        "issues": []
      },
      "dkim": {
        "status": "pass",
        "selectorsChecked": [
          "google"
        ],
        "selectorsFound": [
          "google"
        ],
        "issues": []
      },
      "dmarc": {
        "status": "pass",
        "record": "v=DMARC1; p=reject",
        "policy": "reject",
        "reportsConfigured": true,
        "issues": []
      },
      "riskLevel": "low",
      "signals": []
    },
    "dnsbl": {
      "status": "clear",
      "checks": {
        "total": 40,
        "listed": 0,
        "failed": 0
      },
      "riskLevel": "low",
      "listings": [],
      "signals": []
    },
    "whois": {
      "status": "registered",
      "createdAt": "1995-08-14T00:00:00Z",
      "expiresAt": "2027-08-13T00:00:00Z",
      "domainAgeDays": 11320,
      "riskLevel": "low",
      "registrar": "Example Registrar",
      "updatedAt": "2026-01-10T00:00:00Z",
      "daysUntilExpiry": 367,
      "nameServers": [
        "ns1.company.com",
        "ns2.company.com"
      ],
      "privacyProtected": true,
      "signals": []
    }
  },
  "creditsCharged": 2,
  "creditsRemaining": 498,
  "meta": {
    "modelVersion": "deliverability-v2"
  }
}

Response field reference

Field	Type	Meaning
`email`	string	Normalized email address that was checked.
`verificationType`	string	Canonical quick, standard, or deepcheck type that produced the response.
`addressStatus`	string	Address-level result: valid, invalid, or unknown.
`mailbox`	object	Mailbox result, structured signals, and Deepcheck SMTP evidence. Quick and Standard report not_checked.
`risk`	object	Actual detected risk level and structured signals. Omitted checks do not create risk.
`creditsCharged`	number	Actual charge for this request. Refunded when a required result is unknown.
`creditsRemaining`	number	Account balance after the charge or unknown-result refund.
`score`	number	Deliverability score from 0 to 100. Available only for Deepcheck.
`confidence`	string	Confidence in the Deepcheck deliverability verdict. Omitted for Quick and Standard.
`details`	object	Tier-specific validation results. Its child groups are listed below.

Field availability by type

Field or group	Quick	Standard	Deepcheck
`addressStatus, mailbox, risk, signals`	Included	Included	Included
`creditsCharged, creditsRemaining, meta`	Included	Included	Included
`score and confidence`	—	—	Included
`Syntax, domain, MX, disposable, role, person, classification, TLD risk`	Summary	Summary	Full evidence
`ESP, parking, authentication, DNSBL, WHOIS`	—	Summary	Full evidence
`SMTP mailbox and catch-all`	Not checked	Not checked	Included

details.roleBased.status is detected, not_detected, or not_checked. Matches include a canonical role and category. Standard adds confidence; Deepcheck adds structured supporting signals.

details.person reports firstName, lastName, nameConfidence, and a gender value of male, female, ambiguous, or unknown. Quick and standard also return genderConfidence and genderProbability when a probability is available. They intentionally omit internal dataset and parser diagnostics. Deepcheck adds a customer-readable derivation and structured signals. Treat this as probabilistic enrichment, never verified personal identity.

details.emailProvider.routingCategory is designed for provider-aligned sending and is google, microsoft, other, or unknown. Only route on Google or Microsoft when confidence is high. A security gateway, forwarding service, or mixed highest-priority MX tier intentionally returns unknown. The routing decision always comes from primaryProvider; observedProvidersalso lists recognized lower-priority providers. Use hasSecondaryProvider to flag migrations or heterogeneous fallback configurations without routing on them. Deepcheck responses add every normalized MX host, priority, and whether that record is primary. “Observed” means discovered in DNS; it does not claim that SMTP successfully contacted every backup host.

Scoring semantics

Only Deepcheck exposes a score and confidence because it performs the mailbox check required for a deliverability verdict. Domain trust, sender security, role detection, and person enrichment remain supporting evidence and never claim that a recipient mailbox exists.MailTooth keeps model dimensions, factors, weights, thresholds, and coverage internal.

Credits and billing behavior

Credits never expire. MailTooth reserves the selected type's cost before verification and reports the final charge in the response. Completed requested outcomes retain the charge. Quick and Standard are chargeable when address validation completes even though mailbox status is intentionally not_checked. An unknown required address result—or an unknown Deepcheck mailbox result—is automatically refunded before the response is returned.

Type	Known result	Unknown result
`quick`	0.5 credit	0 credits
`standard`	1 credit	0 credits
`deepcheck`	2 credits	0 credits

One-time credit packs

New accounts start with 100 free credits. Purchased packs are added to the same balance and never expire. Growth is the most popular option, while Scale provides the best published-pack value.

Pack	Price	Credits	Quick	Standard	Deepchecks
Starter	$11	3,600	7,200	3,600	1,800
Growth · Most popular	$27	10,200	20,400	10,200	5,100
Pro	$72	32,600	65,200	32,600	16,300
Scale · Best value	$111	55,000	110,000	55,000	27,500

Custom purchase pricing

Custom packs accept a USD amount of at least $111. Whole credits are calculated from the matching tier, with partial credits rounded down. Amounts below $111 must use a standard plan.

Dollar amount	Per credit	Per Deepcheck
$111–$299.99	$0.002018	$0.00403
$300–$499.99	$0.00180	$0.00360
$500 or more	$0.00160	$0.00320

Custom quote and checkout fields

GET /v1/billing/quote?dollarAmount=300

POST /v1/billing/checkout-sessions
{"customDollarAmount": 300}

Unknown result · refunded

{
  "email": "person@temporary-network.example",
  "verificationType": "standard",
  "addressStatus": "unknown",
  "mailbox": {
    "status": "not_checked",
    "signals": [
      {
        "code": "mailbox_check_skipped_unknown_address",
        "severity": "info",
        "message": "Mailbox verification was skipped because address-level checks were inconclusive.",
        "action": "retry"
      }
    ]
  },
  "risk": {
    "level": "unknown",
    "signals": []
  },
  "signals": [
    {
      "code": "address_result_unknown",
      "severity": "info",
      "message": "The DNS lookup did not produce a conclusive result.",
      "action": "retry"
    }
  ],
  "details": {
    "syntax": {
      "status": "valid"
    },
    "domain": {
      "status": "unknown"
    },
    "mx": {
      "status": "unknown"
    }
  },
  "creditsCharged": 0,
  "creditsRemaining": 100,
  "meta": {
    "modelVersion": "deliverability-v2"
  }
}

Cached results use the same price as newly executed checks. A request rejected before verification—for example an invalid API key, rate limit, or insufficient balance—is not charged.

Response headers

Successful authenticated requests include current rate and credit information so clients can monitor capacity without another API call.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute for this key.
`X-RateLimit-Remaining`	Requests remaining in the current rate-limit window.
`X-RateLimit-Reset`	ISO 8601 timestamp when the current window resets.
`X-Credits-Remaining`	Lifetime credits remaining after this request and any unknown-result refund.
`X-API-Key-Remaining`	Calls remaining in this API key's total limit.
`Retry-After`	Seconds to wait after a per-minute rate-limit response.

Errors

Error responses use JSON and include a numeric status code plus a human-readable message. Limit errors also include a stable machine-readable code.

HTTP	Meaning	When it happens
400	Invalid request	The email is missing, malformed, or the body contains unsupported fields.
401	Unauthorized	The x-api-key header is missing, invalid, inactive, or belongs to an inactive account.
402	Insufficient credits	The account balance is lower than the selected verification type's cost.
429	Limit exceeded	The key exceeded its per-minute or lifetime request limit.
500	Server error	The verification could not be completed because of an unexpected error.
503	Temporarily unavailable	A required service, such as rate limiting, is temporarily unavailable.

Authentication error

{
  "statusCode": 401,
  "message": "A valid x-api-key header is required.",
  "error": "Unauthorized"
}

Ready to integrate?

Create an API key and make a request.

Open API keys

Email verification API