API Documentation
Verify emails from your own code.
A JSON REST API for single and bulk email verification, blocklist monitoring and header analysis. Every endpoint below is documented from how it behaves today.
Overview
The Waytoinbox REST API lets you run email verification and a few monitoring checks from your own code. Requests and responses use JSON, except where an endpoint accepts a file upload.
| Endpoint | What it does |
|---|---|
POST /api/validate/email/ | Verify one email address |
POST /api/validate/bulk/ | Submit a list of addresses as a bulk job |
GET /api/validate/status/<job_id>/ | Check a bulk job’s progress |
GET /api/validate/results/<job_id>/ | Read a bulk job’s results, page by page |
POST /api/blocklist/ip/ | Add an IP address to blocklist monitoring |
POST /api/blocklist/domain/ | Add a domain to blocklist monitoring |
POST /api/header-analysis/ | Analyze a raw email header |
Examples on this page use the base URL https://waytoinbox.com. Addresses in examples use reserved .example domains.
Authentication
Send your API key in the X-API-Key request header. Send it as a header only; the API does not accept keys in the URL.
X-API-Key: YOUR_API_KEY| Situation | Response |
|---|---|
| Key missing (bulk status, results and submit) | 401 with {"error": "API key required. Send it via the X-API-Key header."} |
| Key invalid or inactive, or its account is deactivated | 403 with {"error": "Invalid or inactive API key"} |
Keys belong to an account. This 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.
Credits and billing
API calls spend the same credits as the app. When a balance is too low the request is refused and nothing is processed.
| Endpoint | What is charged |
|---|---|
| Verify one email | One Email Validation credit per address |
| Bulk validation | One Email Validation credit per unique address, charged once at submission |
| IP and domain blocklist | One credit of that service for each IP or domain you add |
| Header analysis | Credits from your Email Header Analyzer balance |
Email Validation credits never expire. Credits for the other services are valid for 30 days from the purchase date. See the pricing page for totals.
Verify one email
/api/validate/email/Verifies a single address and returns its result.
Request
| Part | Value |
|---|---|
| Headers | X-API-Key, Content-Type: application/json |
| Body | {"email": "address"} |
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"}'Response
{
"status": "ok",
"email": "maya@northwind.example",
"result": "Valid",
"reason": "…",
"mx_record": "…",
"record_id": 123,
"credits": 4999
}| Field | Meaning |
|---|---|
status | ok when the check completed |
email | The address that was checked |
result | The verification result, for example Valid |
reason | The reason for the result |
mx_record | The MX record found for the address |
record_id | The id of the saved record |
credits | Your remaining Email Validation credits |
Errors
| 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 |
Bulk validation: submit
/api/validate/bulk/Submits a list of addresses as one job. Send either a file or a JSON list. The job runs in the background; use the status and results endpoints to follow it.
Request
| Option | How |
|---|---|
| File upload | multipart/form-data with a file field. Accepted formats: CSV, XLSX, JSON, TXT |
| JSON body | {"emails": ["a@example.com", "b@example.com"]}. Strings only |
Idempotency-Key header (optional) | 1 to 128 printable ASCII characters. Keys are matched case-insensitively |
curl -X POST https://waytoinbox.com/api/validate/bulk/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Idempotency-Key: import-2026-q3-001" \
-H "Content-Type: application/json" \
-d '{"emails": ["a@northwind.example", "b@northwind.example"]}'Credits are charged once, at submission, for the unique addresses (trimmed and compared case-insensitively; blanks are ignored; addresses with invalid syntax still count). Duplicates are removed before validation. Retrying the same request (same key and payload, or the same payload within 15 minutes when no key is sent) returns the original job and charges nothing.
Response
{
"job_id": "…",
"total": 2,
"status": "…",
"status_url": "…",
"results_url": "…",
"submitted_rows": 2,
"blank_ignored": 0,
"duplicates_removed": 0,
"unique_emails": 2,
"credits_charged": 2,
"credits_remaining": 4998,
"billing_state": "…",
"idempotent_replay": false
}Errors
Errors use the body {"status": "error", "code": …, "error": …, "message": …} (some add fields such as need, current or existing_job_id).
| HTTP | Codes |
|---|---|
| 400 | invalid_json, invalid_email_item, invalid_emails, no_emails, email_too_long, unsupported_format, unsupported_content, unreadable_file, empty_file, no_email_column, invalid_request, invalid_idempotency_key |
| 401 / 403 | 401 key missing; 403 api_key_no_owner, service_disabled, or an invalid key |
| 402 | insufficient_credits, with need and current |
| 409 | idempotency_key_conflict, duplicate_submission (same payload under a different key within the 15-minute window), request_in_progress, submission_refunded (that key belongs to a submission that failed and was refunded; resubmit under a new key) |
| 413 | payload_too_large, unique_limit_exceeded |
| 429 | rate_limited, active_job_limit, both with a Retry-After header |
Bulk validation: status
/api/validate/status/<job_id>/Returns the progress and counts for one bulk job. A job that does not exist, or belongs to another account, is reported as not found.
curl https://waytoinbox.com/api/validate/status/JOB_ID/ \
-H "X-API-Key: YOUR_API_KEY"{
"job_id": "…",
"status": "…",
"total": 2,
"valid": 1,
"invalid": 1,
"unknown": 0,
"others": 0,
"valid_pct": 50.0,
"invalid_pct": 50.0,
"progress_pct": 100.0,
"started_at": "…",
"completed_at": "…",
"duration": "0m 12s"
}Bulk validation: results
/api/validate/results/<job_id>/Returns a job’s results, one page at a time.
| Query parameter | Meaning |
|---|---|
page | Page number, a whole number of 1 or more |
page_size | Results per page, a whole number of 1 or more. The default is 100 and the maximum is 1000 |
result | Optional filter on the result, for example Valid |
A page or page_size that is not a whole number of 1 or more is refused with 400 and the code invalid_pagination.
curl "https://waytoinbox.com/api/validate/results/JOB_ID/?page=1&page_size=100&result=Valid" \
-H "X-API-Key: YOUR_API_KEY"{
"job_id": "…",
"total": 2,
"page": 1,
"page_size": 100,
"total_pages": 1,
"results": [
{
"Win_Id": "…",
"email": "a@northwind.example",
"validation_results": "Valid",
"result_reason": "…"
}
]
}IP blocklist check
/api/blocklist/ip/Adds an IP address to blocklist monitoring and runs the first check. Adding an IP uses one credit; an IP that is already monitored is not charged again.
curl -X POST https://waytoinbox.com/api/blocklist/ip/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ip": "203.0.113.10"}'{
"status": "ok",
"ip": "203.0.113.10",
"ip_id": 12,
"listed_count": 0,
"error_count": 0,
"ip_current_credits": 4
}| Field | Meaning |
|---|---|
listed_count | How many blocklists list the IP |
error_count | How many blocklists could not be checked |
ip_current_credits | Your remaining IP Blocklist credits |
If the IP is already monitored the call returns 200 with {"status": "warning", "message": "IP '…' is already being monitored."}.
| HTTP | Cause |
|---|---|
| 400 | IP missing (IP address is required), not a valid IP (Enter a valid IP address), or invalid JSON |
| 402 | Credits not found for the account |
| 403 | Invalid or inactive key, or the service is switched off for the account |
| 405 | Wrong HTTP method |
| 429 | No credits left |
Domain blocklist check
/api/blocklist/domain/Adds a domain to blocklist monitoring and runs the first check. Adding a domain uses one credit; a domain that is already monitored is not charged again.
curl -X POST https://waytoinbox.com/api/blocklist/domain/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain": "northwind.example"}'{
"status": "ok",
"domain": "northwind.example",
"domain_id": 7,
"listed_count": 0,
"error_count": 0,
"ip_current_credits": 4
}The remaining-credits field is called ip_current_credits in this response too. It reports your remaining Domain Blocklist credits. The name is kept as it is so existing integrations keep working.
| HTTP | Cause |
|---|---|
| 400 | Domain missing (Domain is required), not valid (Enter a valid domain), or invalid JSON |
| 402 | Credits not found for the account |
| 403 | Invalid or inactive key, or the service is switched off for the account |
| 405 | Wrong HTTP method |
| 429 | No credits left |
Header analysis
/api/header-analysis/Analyzes a raw email header.
| Option | How |
|---|---|
| JSON body | {"header": "raw header text"} |
| File upload | multipart/form-data with a header_file field. Only .txt files up to 50 MB |
The input must be at least 30 characters long and include the From:, Received:, Subject: and Date: lines; otherwise it is refused with 400.
curl -X POST https://waytoinbox.com/api/header-analysis/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"header": "Received: from …\nFrom: …\nSubject: …\nDate: …"}'{
"status": "ok",
"credits": 24,
"results": { … }
}credits is your remaining balance and results holds the analysis.
| HTTP | Cause |
|---|---|
| 400 | No header or file, input too short or missing required lines, file larger than 50 MB, a file that is not .txt, or invalid JSON |
| 403 | Invalid or inactive key, or the service is switched off for the account |
| 405 | Wrong HTTP method |
| 429 | No credits left |
| 500 | The analysis could not be completed. Please try again. |
| 503 | {"status": "error", "code": "billing_error", …}: the request could not be completed |
Errors at a glance
Errors are returned as JSON with an HTTP status code. Most include status: "error" and a message; a few older responses use a single error field, so read both.
| HTTP | Meaning |
|---|---|
| 400 | The request could not be understood or the input is invalid |
| 401 | API key missing (bulk status, results and submit) |
| 402 | Not enough credits |
| 403 | Invalid or inactive key, or the service is unavailable for the account |
| 405 | Wrong HTTP method |
| 409 | A bulk submission conflicts with an earlier one |
| 413 | A bulk submission is too large |
| 429 | No credits left (blocklist and header endpoints), or a bulk rate or active-job limit |
| 500 / 503 | The request could not be completed; try again |
Ready to stop bouncing and start landing?
Sign up, verify your email and activate your 7-day free trial — it includes 100 email verifications on us. No credit card required.