Quickstart
Create a key, make one request, read the result. Two minutes, 100 free credits.
1. Get a key
Sign up at app.mailvet.app. Your live key (mv_live_…) and a test key (mv_test_…) are on the first screen. Test keys return realistic fake results and never use credits, so use them in CI.
Keep the key on your server. Never ship it in browser or mobile code; call MailVet from your backend instead.
2. Verify an address
One GET request with the address as the email query parameter.
curl "https://api.mailvet.app/v1/verify?email=dana.reyes@northwind.example" \
-H "Authorization: Bearer mv_live_…"{
"id": "vrf_01JD8X2T7Q",
"email": "dana.reyes@northwind.example",
"status": "done",
"result": "deliverable",
"reason": "catch_all_verified",
"score": 94,
"domain": "northwind.example",
"mx": "aspmx.l.google.com",
"flags": {
"catch_all_domain": true,
"disposable": false,
"role": false,
"free_provider": false
},
"credits_charged": 1,
"took_ms": 2140
}3. Read the result
Branch on result. Use reason when you need the detail, for example to tell a typo (invalid_domain) from a dead mailbox (mailbox_not_found).
deliverable: send.undeliverable: don't send; remove or mark bounced.risky: exists but disposable or full; your policy decides.unknown: no definite answer this time; free, re-run later.
4. Handle pending checks
A small share of catch-all checks take longer than 15 seconds. Those return HTTP 202 with status: "pending". Poll the poll_url, or set a webhook once and receive the result when it's ready. See /docs/webhooks.
A pending response
HTTP/1.1 202 Accepted
{
"id": "vrf_01JD8X9MRC",
"email": "j.okafor@harbor-logistics.example",
"status": "pending",
"result": null,
"poll_url": "https://api.mailvet.app/v1/verify/vrf_01JD8X9MRC",
"credits_charged": 0
}