API Documentation

Check a single email

Request body

Example

curl -X POST https://www.mailtruster.com/api/check-email \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "validation_type": "smtp"}'

Response · 200

{
  "success": true,
  "data": {
    "email": "marie.durand@example.com",
    "validation_type": "smtp",
    "result": "valid",
    "details": null,
    "reasons": [],
    "checks": {
      "syntax": true,
      "dns": true,
      "smtp_port": true,
      "smtp_connection": true,
      "smtp_rcptto": true,
      "smtp": true
    },
    "reason": null,
    "errors": null,
    "role": false,
    "spamtrap": false,
    "disposable": false,
    "free": false,
    "catch_all": false,
    "protected": false,
    "metadata": {
      "validated_at": "2026-08-10 10:15:51 +0000",
      "smtp_host": "203.0.113.10"
    }
  },
  "meta": {
    "request_id": "018e6b3c-...",
    "timestamp": "2026-08-10T10:15:51+00:00",
    "version": "v1"
  }
}

success tells you the request worked. It says nothing about the address — that is data.result. A 200 carrying "result": "invalid" is a perfectly successful request.

The verdict · data.result

Always present, always one of these four. Handle all four — a shortcut such as ["valid","risky"].includes(result) loses the distinction that matters most.

switch (data.result) {
  case "valid":   return send();
  case "risky":   return sendWithCaution();  // look at data.reasons
  case "invalid": return dropContact();
  case "unknown": return scheduleRetry();    // DO NOT delete the contact
}

Response fields

details and reasons values

details is the first entry of reasons, which holds them all in precedence order. This vocabulary is open and may grow — always handle an unrecognised value.

Two orderings worth knowing: spamtrap and disposable outrank unknown (they hold whether or not the mailbox exists), while catch_all and role rank below it (they assume a completed SMTP session). And mailbox_full is unknown, not invalid — the mailbox exists and will become deliverable again. reasons stays exhaustive: a role address that timed out gives result: "unknown", details: "timeout", reasons: ["timeout", "role"].

When the service is saturated

Two distinct events come back as result: "unknown" with checks: {} and an HTTP 200 — never a 502. The four address flags are absent from these responses, so render them as not determined rather than as no.

Treat both like any other unknown: nothing was established, retry later. The address itself is untouched.

Validation types

A verdict only covers what the type checked. Only smtp opens an SMTP session, so for the other three details is null and reasons is []. The address flags are computed for every type — they need no network — but they only influence the verdict in smtp. To spot a throwaway or a role address outside of smtp, read the flags rather than the verdict.

Get quota

Example

curl https://www.mailtruster.com/api/quota

Response · 200

{
  "daily_limit": 100,
  "used": 14,
  "remaining": 86
}

Bulk verification

Async workflow - submit a list, get a job_id per email, then poll each one individually.

1 - Submit a job

curl -X POST https://www.mailtruster.com/api/bulk-check-email \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["alice@example.com", "bob@test.com"],
    "validation_type": "mx"
  }'

Maximum 100 emails per request. Returns 202 Accepted. Nothing is verified yet.

{
  "success": true,
  "data": {
    "results": [
      {
        "email": "ok@example.com",
        "status": "queued",
        "message": "Queued for verification",
        "job_id": "018e6b3c-1111-..."
      },
      {
        "email": "oops",
        "status": "error",
        "message": "Invalid email format",
        "job_id": "018e6b3c-2222-..."
      }
    ]
  },
  "meta": { ... }
}

Every input line gets one entry and its own job_id — there is no batch-level id, poll one result per address. Addresses are verified independently and in no guaranteed order, so results arrive out of order.

A malformed address is rejected immediately with status: "error", is never queued, and costs no quota. Its job_id will never resolve — polling it returns 404 forever. Filter those out of your polling set using this response. Here: poll 018e6b3c-1111-..., never 018e6b3c-2222-....

Quota is consumed at submission, for the count of valid addresses only. A bulk request is all or nothing: if that count exceeds what remains, the whole request is refused with 429 and nothing is queued.

2 - Poll a result

curl https://www.mailtruster.com/api/verification-result/018e6b3c-1111-...

data.result is the record, and it has exactly three keys: email, status and verification. While the job is running there is nothing to serve:

{
  "success": true,
  "data": {
    "job_id": "018e6b3c-1111-...",
    "result": {
      "email": "ok@example.com",
      "status": "processing",
      "verification": null
    }
  },
  "meta": { ... }
}

Once it is finished, verification is exactly the payload of the single check above, key for key — so the same parsing code handles both endpoints:

{
  "success": true,
  "data": {
    "job_id": "018e6b3c-1111-...",
    "result": {
      "email": "ok@example.com",
      "status": "done",
      "verification": {
        "email": "ok@example.com",
        "validation_type": "smtp",
        "result": "valid",
        "details": null,
        "reasons": [],
        "checks": { "syntax": true, "dns": true, "smtp": true },
        "reason": null,
        "errors": null,
        "role": false,
        "spamtrap": false,
        "disposable": false,
        "free": false,
        "catch_all": false,
        "protected": false,
        "metadata": { "validated_at": "..." }
      }
    }
  },
  "meta": { ... }
}

const FINAL_STATUSES = ["done", "error"];   // and nothing else

const { status, verification } = res.data.result;

if (status === "queued" || status === "processing") return pending();
if (status === "error") return technicalFailure();   // verification is null

// status === "done" — verification is the single-check payload
switch (verification.result) {
  case "valid":   return good();
  case "risky":   return warn();          // look at verification.reasons
  case "invalid": return bad();
  case "unknown": return inconclusive();  // do NOT delete the contact
}

Counting for a summary

Count on verification.result, over the records whose status is done. Records in error have no verdict and belong in their own bucket — folding them into invalid misreports technical failures as bad addresses. A defensible breakdown has five buckets: valid, risky, invalid, unknown, error.