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.

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"}'

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.

  1. Get an API key

    Keys belong to an account, and you send yours in the X-API-Key header. It goes in the header only; the API does not accept keys in the URL.

    Getting a key

    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.

    Headerhttp
    X-API-Key: YOUR_API_KEY
  2. 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"}'
  3. Read the result

    A completed check returns status: "ok" with the address, its result (for example Valid), the reason, the mx_record, the saved record_id and your remaining credits. 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.

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

REST API workflow

Bigger lists run as jobs.

For many addresses at once, submit them in one request and follow the job.

  1. Submit

    POST a file (CSV, XLSX, JSON or TXT) or a JSON list to /api/validate/bulk/. The reply is 202 with a job_id, status_url and results_url.

    Bulk submit
  2. Follow the job

    GET /api/validate/status/<job_id>/ for progress and counts: valid, invalid, unknown and others.

    Bulk status
  3. Read the results

    GET /api/validate/results/<job_id>/ one page at a time, optionally filtered by result.

    Bulk results

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.

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

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.