MailQuell email verification API

Quick start

1. create a free account and confirm your email address (200 checks a month are included).
2. In Developer Hub → API keys, create a key. It starts with mq_live_ and is shown once: keep it on your server, never in a web page or a mobile app.
3. Check an address:

curl -X POST https://api.mailquell.com/v1/verify \
  -H "X-API-Key: $MAILQUELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "alex@example.com"}'

Authentication

Send your key with every request, in either header:

X-API-Key: mq_live_YOUR_API_KEY
# or
Authorization: Bearer mq_live_YOUR_API_KEY

• Permissions. A read-only key can read lists, results and credits, but cannot check addresses or start, pause or cancel lists (403 api_key_read_only). Use one for dashboards and reports. Other keys can do everything the API offers.
• Keys belong to the account: a team's keys spend the team's credits. Revoke a key at any time in the Developer Hub; it stops working at once.
• Spending credits needs a confirmed email address (403 email_not_verified).

Verify one address

Checks the syntax, the domain, its mail servers, and asks the mail server whether the mailbox exists (no email is sent). Most answers take a few seconds; allow up to 60 seconds for slow mail servers.

Request body

Response

{
  "email": "alex@example.com",
  "status": "safe",
  "riskLevel": "low",
  "suggestedAction": "safe_to_contact",
  "score": 100,
  "scoreBreakdown": {
    "syntaxScore": 15, "dnsDomainScore": 25, "mxRecordsScore": 25,
    "smtpMailboxScore": 35, "penalties": 0,
    "penaltyReasons": [], "totalScore": 100
  },
  "technicalDetails": {
    "mailboxExists": true, "domainValid": true, "mxRecordsFound": true,
    "mxHost": "mx1.example.com", "smtpReachable": true,
    "smtpCode": 250, "smtpMessage": "2.1.5 OK",
    "disposable": false, "roleAccount": false, "catchAll": false,
    "freeProvider": false, "spfValid": true, "dmarcValid": true,
    "riskSignals": []
  },
  "didYouMean": null,
  "durationMs": 2140,
  "verifiedAt": "2026-10-30T09:12:44.512Z"
}

Cost. 1 credit. Not charged: a badly formed address (answered at once as invalid), an unknown, timeout or blocked answer, and a check that fails on our side (502 verification_failed).

Statuses

Verify a list

Starts a list in the background and answers at once with 201. Up to 50,000 addresses per list and 25 MB per request; 10 lists a minute.

The response holds task (with its id), duplicatesRemoved and reused. The credits for the whole list are taken when it starts. When it ends, addresses still without a clear answer after a second try (a few minutes later) and checks that failed on our side are refunded.

curl -X POST https://api.mailquell.com/v1/bulk \
  -H "X-API-Key: $MAILQUELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter October",
    "emails": [
      { "email": "ann@acme.com", "name": "Ann", "company": "Acme" },
      { "email": "bob@example.org" }
    ]
  }'

Follow and read a list

Pause, resume, cancel

Retention. Per-address results are deleted 20 days after a list finishes; the counters stay. After that, results and exports answer 410 results_expired. Download what you need before.

Account and credits

Who the key belongs to and what it can spend. Integrations call it to test a key.

{
  "email": "you@company.com",
  "name": "Your name",
  "plan": "Free",
  "credits": { "allowanceLeft": 180, "allowancePeriod": "month", "instant": 5000 }
}

allowanceLeft is what remains of the free or plan allowance (renewed every day or month), instant the purchased credits, which never expire. See pricing.

Webhooks

Instead of polling, receive an HTTPS POST when something happens. Add an endpoint in Developer Hub → Webhooks and choose its events; each endpoint has its own signing secret (whsec_…).

POST /your/endpoint
Content-Type: application/json
MailQuell-Event: task.completed
MailQuell-Delivery: 9f0c…        (the same on every retry: use it to ignore duplicates)
MailQuell-Signature: t=1761815564,v1=5257a869e7ec…

{
  "id": "evt_3b1f…",
  "type": "task.completed",
  "created": "2026-10-30T09:12:44.512Z",
  "data": {
    "id": "cmh…", "name": "Newsletter October", "total": 2000, "processed": 2000,
    "counts": { "valid": 1712, "risky": 140, "invalid": 121, "unknown": 27, "errors": 0 },
    "completedAt": "2026-10-30T09:12:44.000Z",
    "resultsPath": "/api/tasks/cmh…/export"
  }
}

Check the signature

v1 is the HMAC-SHA256 of "<t>.<raw body>" with your secret, in hex. Refuse a request whose signature does not match or whose timestamp is more than 5 minutes old.

import crypto from "node:crypto";

// Use the raw request body (before JSON parsing), e.g. express.raw({ type: "application/json" }).
function verifyMailQuell(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=", 2)));
  const t = Number(parts.t);
  if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// verifyMailQuell(req.body.toString("utf8"), req.get("MailQuell-Signature"), process.env.MAILQUELL_WEBHOOK_SECRET)

Delivery

• Answer with any 2xx status within 10 seconds. Redirects are not followed.
• Otherwise we try again after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours (6 attempts over about 7.5 hours), then you are notified in the dashboard. Every delivery is listed in the Developer Hub, where you can send it again.
• The endpoint must use HTTPS on the standard port and a public address.

Rate limits

120 requests per minute per API key (without a key: per IP address), and 10 list uploads per minute. Every response includes:

x-ratelimit-limit: 120
x-ratelimit-remaining: 117
x-ratelimit-reset: 42

Over the limit you get 429 rate_limited with a retry-after header (seconds). For more than a few addresses, send one list with POST /v1/bulk instead of many single checks.

Errors

Errors come back as JSON with an error code, sometimes with details: { "error": "insufficient_credits", "pool": "instant", "needed": 2000 }.

MCP and integrations

• MCP server for AI assistants (Claude, Cursor, VS Code…): https://api.mailquell.com/mcp, with tools verify_email, verify_list, get_list, list_lists and get_credits. Same credits as the API. Setup in Developer Hub → Integrations.
• No code: WordPress and WooCommerce plugin, a form widget for Wix and Ghost, Zapier and n8n, Mailchimp, Brevo and MailerLite list sync, and a Chrome extension.
• Questions about the API: support@mailquell.com.