Documentation API

The Mailtest.me REST API lets you integrate email verification and spam testing into your own tools, scripts and pipelines.

Introduction

The API is available to subscribers from the Pro plan (50 checks/day). All responses are JSON. The base URL for all requests is:

https://mailtest.me

Two features are exposed: email address verification and the spam test (deliverability). Each feature consumes its own daily quota.

Authentication

Every API request must include your API key in the HTTP header X-API-Key :

X-API-Key: mt_votre_cle_api

You can generate your key from your account page. The full key is only shown once, upon creation: store it somewhere safe.

401 — missing or invalid key
403 — insufficient plan (Pro minimum required)

Email verification

Verifies an email address in three steps: syntax (RFC 5322), DNS (MX records), and SMTP (handshake with the server). Returns a confidence score from 0 to 100. Each call is deducted from your daily verification quota.

Verify an address

POST /api/v1/check

Headers

X-API-Key: mt_votre_cle_api Content-Type: application/json

Body (JSON)

{ "email": "test@example.com" }

Response 200

{ "email": "test@example.com", "checks": { "syntax": { "status": "valid", "message": "Syntaxe valide", "detail": "Format RFC 5322 OK" }, "dns": { "status": "valid", "message": "Serveurs MX trouvés", "mx_records": [ { "host": "aspmx.l.google.com", "priority": 1 } ] }, "smtp": { "status": "valid", "message": "Serveur SMTP répond", "server": "aspmx.l.google.com", "response_code": 220 } }, "overall_score": 95, "is_valid": true, "checked_at": "2026-08-12T12:00:00.000000" }

Errors

401 — Missing or invalid API key 403 — Insufficient plan (Pro minimum required) 422 — Invalid email address 429 — Daily verification limit reached

Spam test

The spam test measures the deliverability of your emails (newsletters, transactional emails). The API generates a unique disposable email address; you send your email to it; Mailtest.me analyzes it (SPF, DKIM, DMARC, SpamAssassin, AI content analysis) and returns a score out of 100 with a detailed report.

Each creation call is deducted from your daily spam test quota, independent from the email verification quota (see Rate limits).

How it works

Create a test — call POST /api/v1/spam-test. You get back a unique disposable email address such as spamtest-a1b2c3d4@spamtest.mailtest.me. Each call creates a fresh test: do not reuse an address from a previous test.

Send your email — send the newsletter or transactional email to the disposable address, exactly as you would send it to a real recipient (same SMTP server, same content). The analysis starts automatically upon reception (status analyzing).

Fetch the result — poll GET /api/v1/spam-test/{id} every 3 seconds until the status becomes done. The score and full report are then available.

Test statuses

Status	Description
`waiting`	Waiting for the email to arrive
`analyzing`	Email received, analysis in progress
`done`	Analysis complete, result available
`error`	Analysis failed

Create a test

POST /api/v1/spam-test

Creates a new spam test and returns the disposable address. No request body required.

Headers

X-API-Key: mt_votre_cle_api

Response 200

{ "id": "a1b2c3d4", "address": "spamtest-a1b2c3d4@spamtest.mailtest.me", "status": "waiting", "remaining": 4 }

remaining : number of spam tests still available today for your account.

Errors

401 — Missing or invalid API key 403 — Insufficient plan (Pro minimum required) 429 — Daily spam test limit reached

Send the test email

This step does not go through the API: simply send your email to the disposable address returned in the previous step, from the server or service (ESP, SMTP relay, newsletter tool) you want to evaluate.

The disposable address only accepts the first received email: send only one.
The analysis starts automatically upon reception and usually takes a few seconds.
Keep the id of the test to poll the result.

Fetch the result

GET /api/v1/spam-test/{id}

Returns the current status of the test and, once the analysis is complete, the full report. The test must have been created with the same API key.

Headers

X-API-Key: mt_votre_cle_api

Response 200 — analysis in progress

{ "id": "a1b2c3d4", "address": "spamtest-a1b2c3d4@spamtest.mailtest.me", "status": "analyzing", "score": null, "subject": "Votre campagne de juillet", "sender": "newsletter@example.com", "result": null }

Response 200 — analysis complete

{ "id": "a1b2c3d4", "address": "spamtest-a1b2c3d4@spamtest.mailtest.me", "status": "done", "score": 87, "subject": "Votre campagne de juillet", "sender": "newsletter@example.com", "result": { "score": 87, "grade": "Excellent", "summary": "0 problème(s) critique(s), 2 avertissement(s) sur 12 points vérifiés.", "findings": [ { "severity": "warning", "category": "DKIM", "message": "Signature DKIM absente", "explanation": "...", "solution": "..." } ], "ai": { "content_score": 82, "suggestions": [ "..." ] }, "meta": { "from": "newsletter@example.com", "sender_domain": "example.com", "sender_ip": "203.0.113.10", "spamassassin_score": 1.8 } } }

Errors

401 — Missing or invalid API key 403 — Insufficient plan, or test owned by another account 404 — Test not found

Rate limits

Email verification and spam test quotas are independent and reset every day at midnight (UTC).

Plan	Verifications / day	Spam tests / day	API access
Free	3	1 (per IP)	No
Starter (10/j)	10	2	No
Pro (50/j)	50	5	Yes
Business (100/j)	100	10	Yes
Enterprise (500/j)	500	25	Yes

Note — the Starter plan (10/day) includes 2 spam tests per day through the web interface, but has no API access. API access starts at the Pro plan.

Error codes

Errors follow HTTP conventions. The response body contains a detail descriptive field.

Code	Description
`401`	Missing or invalid API key.
`403`	Insufficient plan (Pro minimum), or attempt to access a test owned by another account.
`404`	Resource not found (unknown test id).
`422`	Invalid request body (e.g. malformed email address).
`429`	Daily quota reached. The message states which one (verifications or spam tests).
`500`	Internal error. Try again later.

Examples

cURL

Email verification

curl -X POST https://mailtest.me/api/v1/check \ -H "X-API-Key: mt_votre_cle_api" \ -H "Content-Type: application/json" \ -d '{"email": "test@example.com"}'

Spam test — full workflow

# Step 1 — create the test curl -X POST https://mailtest.me/api/v1/spam-test \ -H "X-API-Key: mt_votre_cle_api" # → {"id": "a1b2c3d4", "address": "spamtest-a1b2c3d4@spamtest.mailtest.me", ...} # Step 2 — send your email to the returned address # Step 3 — fetch the result (repeat every 3 s) curl https://mailtest.me/api/v1/spam-test/a1b2c3d4 \ -H "X-API-Key: mt_votre_cle_api"

Python

Spam test with polling

import time import requests BASE = "https://mailtest.me" HEADERS = {"X-API-Key": "mt_votre_cle_api"} # 1. Créer le test r = requests.post(f"{BASE}/api/v1/spam-test", headers=HEADERS) r.raise_for_status() test = r.json() print("Envoyez votre email à :", test["address"]) # 2. ... envoyez l'email depuis votre serveur SMTP ... # 3. Poller le résultat while True: time.sleep(3) r = requests.get( f"{BASE}/api/v1/spam-test/{test['id']}", headers=HEADERS, ) r.raise_for_status() data = r.json() if data["status"] in ("done", "error"): break print("Score :", data["score"], "/100")