Solutions · Developers
Verify addresses from your own code.
Verify addresses from your own code with a REST call and an API key.
Examples use reserved .example domains.
curl -X POST https://waytoinbox.com/api/validate/email/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "maya@northwind.example"}'Quick-start example
From key to result in three steps.
This is the whole single-address workflow. Everything else in the API follows the same pattern.
-
Get an API key
Keys belong to an account, and you send yours in the
X-API-Keyheader. It goes in the header only; the API does not accept keys in the URL.Getting a keyThis page does not describe a way to create a key yourself, because no self-service key page is documented. If you need API access, ask through the Help Center.
Headerhttp X-API-Key: YOUR_API_KEY -
Send a request
POST a JSON body with the address to
/api/validate/email/. Each verification uses one Email Validation credit.Without a key, and without a signed-in session, the same endpoint treats the call as a guest check: the free check on the homepage, limited to 5 per IP address per day.
Example requestbash curl -X POST https://waytoinbox.com/api/validate/email/ \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "maya@northwind.example"}' -
Read the result
A completed check returns
status: "ok"with the address, itsresult(for exampleValid), thereason, themx_record, the savedrecord_idand your remainingcredits. The values shown as…depend on the address.200 OKjson { "status": "ok", "email": "maya@northwind.example", "result": "Valid", "reason": "…", "mx_record": "…", "record_id": 123, "credits": 4999 }
Errors
Handle what can go wrong.
Errors are JSON with an HTTP status. Most include status: "error" and a message; a few older responses use a single error field, so read both.
A 402 means that service has no credits left. Email Validation credits never expire; credits for the other services are valid for 30 days from the purchase date, so there a 402 can also mean the credits you bought have expired. See pricing.
| HTTP | Body | Cause |
|---|---|---|
| 400 | {"status": "error", "message": "Email is required"} | No email in the request |
| 400 | {"error": "Invalid JSON body"} | The body is not valid JSON |
| 402 | {"status": "error", "message": "Insufficient Email Validation credits.", "need": 1, "current": 0} | Not enough credits; nothing was validated |
| 403 | {"error": "Invalid or inactive API key"} | Key invalid or inactive |
| 403 | {"status": "error", "message": "This service is currently unavailable for your account."} | The service is switched off for the account |
| 405 | {"error": "POST required"} | Wrong HTTP method |
| 500 | {"status": "error", "message": …} | The check could not be completed |
REST API workflow
Bigger lists run as jobs.
For many addresses at once, submit them in one request and follow the job.
Submit
POST a file (CSV, XLSX, JSON or TXT) or a JSON list to
Bulk submit/api/validate/bulk/. The reply is202with ajob_id,status_urlandresults_url.Follow the job
GET
Bulk status/api/validate/status/<job_id>/for progress and counts: valid, invalid, unknown and others.Read the results
GET
Bulk results/api/validate/results/<job_id>/one page at a time, optionally filtered byresult.
Credits are charged once, at submission, for the unique addresses. An Idempotency-Key header makes a retried submission safe: the original job is returned and nothing more is charged.
What the API covers
Seven endpoints.
Verification, two blocklist checks and header analysis. Each links to its full reference.
- POST
/api/validate/email/Verify one email address - POST
/api/validate/bulk/Submit a list as a bulk job - GET
/api/validate/status/<job_id>/Check a bulk job’s progress - GET
/api/validate/results/<job_id>/Read a job’s results, page by page - POST
/api/blocklist/ip/Add an IP to blocklist monitoring - POST
/api/blocklist/domain/Add a domain to blocklist monitoring - POST
/api/header-analysis/Analyze a raw email header
Benefits
Dashboard when you want it, API when you need it.
Plain REST and JSON
POST JSON, read JSON. Examples in the documentation are curl requests you can run as they are.
The same credits as the app
API calls spend the same credits as the dashboard, and a call is refused, with nothing processed, when the balance is too low.
More than verification
Add IPs and domains to blocklist monitoring and analyze email headers from the same API.
Ideas for what to build
- Check an address when someone signs up
- Clean a CRM export before a campaign
- Add a new sending IP to monitoring
- Analyze a header from a support ticket
Keep going
Documentation and help.
Ready to stop bouncing and start landing?
Sign up, verify your email and activate your 7-day free trial to try every service in the app. No credit card required.