Asynchronous REST API

Email Verification API

Create a single-address job or upload a CSV or XLSX file, then poll the returned status and results URLs. API-key calls require paid status and the appropriate key scopes.

Open API Playground Authenticated API Docs Use Bulk Upload Instead

Authentication and actual endpoints

Send Authorization: Bearer mt_your_key. X-API-Key: mt_your_key is also accepted. Keys are stored as hashes and can be scoped with verify:write and verify:read.

Method	Path	Purpose
GET	`/api/me`	Test the key and identify the account.
POST	`/api/verify/single`	Create a one-address job from JSON.
POST	`/api/verify/bulk`	Create a job from multipart CSV or XLSX.
GET	`/api/jobs/{job_id}/status`	Poll state, progress, and counts.
GET	`/api/jobs/{job_id}/results?page=1`	Read paginated result objects.

Single verification examples

A successful submission returns HTTP 202, not a final verdict. Store the job ID and poll the URLs in the response.

cURL

curl -X POST https://mailthentic.com/api/verify/single \
  -H "Authorization: Bearer mt_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com"}'

JavaScript

const response = await fetch(
  "https://mailthentic.com/api/verify/single",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer mt_your_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email: "person@example.com" }),
    signal: AbortSignal.timeout(10000),
  },
);
if (!response.ok) throw new Error(await response.text());
const job = await response.json();

Python

import requests

response = requests.post(
    "https://mailthentic.com/api/verify/single",
    headers={"Authorization": "Bearer mt_your_key"},
    json={"email": "person@example.com"},
    timeout=10,
)
response.raise_for_status()
job = response.json()

PHP

$ch = curl_init(
  "https://mailthentic.com/api/verify/single"
);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 10,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer mt_your_key",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "email" => "person@example.com"
  ]),
]);
$body = curl_exec($ch);

Submission response

{
  "job_id": "uuid",
  "status_url": "/api/jobs/uuid/status",
  "results_url": "/api/jobs/uuid/results"
}

Bulk file verification

Submit multipart form data with a file field. Supported formats are CSV and XLSX. Account credits, concurrency, and tier-specific job limits apply.

curl -X POST https://mailthentic.com/api/verify/bulk \
  -H "Authorization: Bearer mt_your_key" \
  -F "file=@contacts.csv"

This is a file endpoint, not a JSON array batch endpoint. The response includes job_id, total_items, status_url, and results_url.

Polling, timeouts, and retries

Set a short connection timeout on submission and a separate overall workflow deadline.
Poll status_url with increasing intervals until state is done or failed.
Retry HTTP 429 and transient 5xx responses with exponential backoff and jitter.
Do not retry 400, 401, 402, 403, or 413 until the input, key, payment status, scope, or file size condition is corrected.
Make your own operation idempotent. A timed-out submission can have reached the server even when the client missed its response.

The public contract does not define a fixed requests-per-second number. Do not build against an invented limit. Respect returned 429 responses and the plan-aware bulk concurrency rules.

Result interpretation

The result object includes the stored status, reason, confidence score and optional breakdown, syntax and DNS fields, MX provider and hosts, SMTP signals, catch-all, flags, and SPF, DKIM, and DMARC context.

Bucket	Examples	Integration action
Valid	`deliverable_confirmed`, `deliverable_unconfirmed`	Inspect confirmation detail for ambiguous providers.
Risky	Catch-all or missing authentication statuses	Route to a documented review policy.
Invalid	Syntax, domain, no MX, disposable, or permanent rejection	Reject or correct the source record.
Unknown	Temporary DNS or SMTP uncertainty	Retry later or use email confirmation.

Treat unknown as unresolved, not invalid. A confidence score is not a promise of inbox placement. The verification status guide maps each bucket and stored status to a practical application decision.

Security and common patterns

Keep keys on the server. Do not expose them in browser JavaScript or a mobile binary.
Create separate least-privilege keys for services and rotate or revoke them from the dashboard.
Validate syntax locally before spending a credit.
Use email confirmation when ownership matters or a provider remains ambiguous.
Store only the result fields and personal data your workflow needs.

API or bulk upload?

Use the API at signup, checkout, import, or another product boundary. Use the web bulk verifier for an existing file that an operator needs to review. The decision guide covers hybrid workflows.

Open API Playground Read API Docs