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.

EndpointWhat 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.

Headerhttp
X-API-Key: YOUR_API_KEY
SituationResponse
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 deactivated403 with {"error": "Invalid or inactive API key"}
Getting an 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.

EndpointWhat is charged
Verify one emailOne Email Validation credit per address
Bulk validationOne Email Validation credit per unique address, charged once at submission
IP and domain blocklistOne credit of that service for each IP or domain you add
Header analysisCredits from your Email Header Analyzer balance
Credit validity

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

POST/api/validate/email/

Verifies a single address and returns its result.

Request

PartValue
HeadersX-API-Key, Content-Type: application/json
Body{"email": "address"}
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"}'

Response

200 OKjson
{
  "status": "ok",
  "email": "maya@northwind.example",
  "result": "Valid",
  "reason": "…",
  "mx_record": "…",
  "record_id": 123,
  "credits": 4999
}
FieldMeaning
statusok when the check completed
emailThe address that was checked
resultThe verification result, for example Valid
reasonThe reason for the result
mx_recordThe MX record found for the address
record_idThe id of the saved record
creditsYour remaining Email Validation credits

Errors

HTTPBodyCause
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

POST/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

OptionHow
File uploadmultipart/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
Example request (JSON body)bash
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"]}'
How billing and retries work

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

202 Acceptedjson
{
  "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).

HTTPCodes
400invalid_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 / 403401 key missing; 403 api_key_no_owner, service_disabled, or an invalid key
402insufficient_credits, with need and current
409idempotency_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)
413payload_too_large, unique_limit_exceeded
429rate_limited, active_job_limit, both with a Retry-After header

Bulk validation: status

GET/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.

Example requestbash
curl https://waytoinbox.com/api/validate/status/JOB_ID/ \
  -H "X-API-Key: YOUR_API_KEY"
200 OKjson
{
  "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

GET/api/validate/results/<job_id>/

Returns a job’s results, one page at a time.

Query parameterMeaning
pagePage number, a whole number of 1 or more
page_sizeResults per page, a whole number of 1 or more. The default is 100 and the maximum is 1000
resultOptional 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.

Example requestbash
curl "https://waytoinbox.com/api/validate/results/JOB_ID/?page=1&page_size=100&result=Valid" \
  -H "X-API-Key: YOUR_API_KEY"
200 OKjson
{
  "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

POST/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.

Example requestbash
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"}'
200 OKjson
{
  "status": "ok",
  "ip": "203.0.113.10",
  "ip_id": 12,
  "listed_count": 0,
  "error_count": 0,
  "ip_current_credits": 4
}
FieldMeaning
listed_countHow many blocklists list the IP
error_countHow many blocklists could not be checked
ip_current_creditsYour remaining IP Blocklist credits

If the IP is already monitored the call returns 200 with {"status": "warning", "message": "IP '…' is already being monitored."}.

HTTPCause
400IP missing (IP address is required), not a valid IP (Enter a valid IP address), or invalid JSON
402Credits not found for the account
403Invalid or inactive key, or the service is switched off for the account
405Wrong HTTP method
429No credits left

Domain blocklist check

POST/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.

Example requestbash
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"}'
200 OKjson
{
  "status": "ok",
  "domain": "northwind.example",
  "domain_id": 7,
  "listed_count": 0,
  "error_count": 0,
  "ip_current_credits": 4
}
A field name to be aware of

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.

HTTPCause
400Domain missing (Domain is required), not valid (Enter a valid domain), or invalid JSON
402Credits not found for the account
403Invalid or inactive key, or the service is switched off for the account
405Wrong HTTP method
429No credits left

Header analysis

POST/api/header-analysis/

Analyzes a raw email header.

OptionHow
JSON body{"header": "raw header text"}
File uploadmultipart/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.

Example requestbash
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: …"}'
200 OKjson
{
  "status": "ok",
  "credits": 24,
  "results": { … }
}

credits is your remaining balance and results holds the analysis.

HTTPCause
400No header or file, input too short or missing required lines, file larger than 50 MB, a file that is not .txt, or invalid JSON
403Invalid or inactive key, or the service is switched off for the account
405Wrong HTTP method
429No credits left
500The 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.

HTTPMeaning
400The request could not be understood or the input is invalid
401API key missing (bulk status, results and submit)
402Not enough credits
403Invalid or inactive key, or the service is unavailable for the account
405Wrong HTTP method
409A bulk submission conflicts with an earlier one
413A bulk submission is too large
429No credits left (blocklist and header endpoints), or a bulk rate or active-job limit
500 / 503The 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.