Email API / Integration guide

Your first
verification.

Send JSON over HTTPS from your server. Authenticate with the API key issued after checkout.

curl https://api.plethorasolutions.llc/api/email/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Read the result.

The response below illustrates the field structure. Actual results depend on the address and the domain's current DNS records.

{
  "valid": true,
  "email": "[email protected]",
  "syntax_valid": true,
  "domain_exists": true,
  "mx_records": ["mail.example.com"],
  "is_disposable": false,
  "role_based": false
}

valid is true when syntax passes, the domain has mail records, and the domain is not recognized as disposable. A role-address flag is informational and does not by itself make the result invalid.

These checks do not establish that a particular mailbox exists or guarantee that it will accept a message.

Choose the right check.

The two single-address endpoints accept a JSON object with an email string between 3 and 254 characters after trimming surrounding whitespace. Addresses are normalized to lowercase.

Send a batch. Keep control.

Create a job with one JSON request. The API returns 202, a private job_id, and a Location header. Only the API key that created a job can read or delete it.

curl https://api.plethorasolutions.llc/api/email/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"verify","emails":["[email protected]","[email protected]"]}'

Poll the URL in Location every few seconds until status is completed or failed. Fetch /results?offset=0&limit=100 for ordered item results. Each item has its own status, result, or stable error_code, so one temporary DNS failure does not hide the other outcomes.

Starter and legacy Professional jobs accept 100 addresses; Growth and legacy Agency accept 500; Business, Scale, and Volume accept 1,000. At most three jobs may be active for one key. A job is accepted only when its item count fits the currently remaining monthly allowance. Concurrent traffic can still exhaust quota while a job runs; unprocessed items then report QUOTA_EXCEEDED.

Batch addresses and results are held in private service storage only for job processing and retrieval. They expire automatically after 24 hours. Send DELETE when you are finished to erase them sooner.

Count requests, not surprises.

Starter includes 10,000 checks per billing period ($19/month), Growth 50,000 ($49/month), and Business 250,000 ($149/month). Scale includes 1,000,000 ($399/month) and Volume 5,000,000 ($1,499/month). Compare plans.

Each successful email endpoint response consumes one check, including a response that reports an invalid address. Checking account usage does not consume email quota. Unused allowances do not roll over. There are no automatic overage charges.

X-Quota-Warning appears at 80_percent, 90_percent, or exhausted. Account usage also returns this warning (or null). Your account shows the warning when you check usage. Existing Starter subscriptions receive the larger allowance without changing their price, keys, renewal date, or already-used checks. Legacy Professional and Agency plans keep their existing allowances.

A temporary DNS failure returns 503 DNS_UNAVAILABLE and does not consume a verification. The request still counts toward short-term rate limits.

Per-key limits are Starter 30, Growth 60, Business 90, Scale 120, and Volume 180 requests per minute. Legacy Professional/Agency and operator keys remain at 30. Both email endpoints share this allowance. X-RateLimit-Limit identifies your customer key's per-minute limit.

A shared application limit of 180 email requests per minute per IP also applies. Edge protection can reject bursts even within these per-minute limits; spread calls evenly and respect Retry-After. Creating a job counts toward the short-term request limit; each completed address counts toward monthly quota. Status polling is separately bounded at 120 requests per minute per key and 600 per IP. Monthly quota is not a speed or completion-time guarantee.

Know what failed. Know what to do.

An HTTP 200 means the check completed, not that the address is valid. Read valid in the result. A completed check that finds no mail records can return 200 with valid: false; a resolver timeout returns 503 DNS_UNAVAILABLE instead. Do not discard an address because a lookup was temporarily unavailable.

Errors generated by this API use the following JSON structure. The support reference is an illustrative example:

{
  "detail": "The email domain lookup is temporarily unavailable.",
  "code": "DNS_UNAVAILABLE",
  "request_id": "0123456789abcdef0123456789abcdef",
  "retryable": true,
  "next_action": "This is not a verdict on the email address. Wait briefly, then retry with backoff."
}

Use the stable code for program logic; human-readable detail and next_action may be clarified over time. Errors repeat the code in X-Error-Code. The API supplies an X-Request-ID on responses and repeats it as request_id in errors. Save this reference when contacting support, along with the error code and approximate time. Never send your API key, recovery code, or checkout link.

Retry deliberately.

retryable: true means another attempt may succeed; it is not a promise of success. Respect Retry-After (seconds), then use bounded retries with increasing delay and jitter. Do not retry an unchanged request rejected for invalid input or credentials.

Checkout redemption, key rotation, and account recovery change credentials. If a response is interrupted or an unexpected server error occurs, the operation may already have completed. Contact support before repeating it. Do not make a second payment to resolve a checkout error.

Checkout and account errors.

CHECKOUT_PENDING (409) means payment confirmation is still processing; wait briefly and resubmit the same verification. CHECKOUT_ALREADY_REDEEMED (409) means use your saved credentials or account recovery. CHECKOUT_EXPIRED (410) requires support. For CHECKOUT_VERIFICATION_FAILED or RECOVERY_VERIFICATION_FAILED (400), check the purchase email and the original confirmation link or latest recovery code. CHECKOUT_RATE_LIMITED, RECOVERY_RATE_LIMITED, and ROTATION_RATE_LIMITED (429) include a waiting period in Retry-After.

Cloudflare or another network intermediary can reject a request before it reaches the API. Such responses may be HTML and may not have this error structure or an API request ID. Check the HTTP status and content type before parsing JSON; retain any edge-provided reference separately. Never include credentials in diagnostic logs.

Keep the key on your server.

Pass your key in the X-API-Key header. Do not embed it in public browser code, URLs, or a public repository. Save the recovery code separately when checkout first reveals it.

Use your account to rotate or recover credentials and manage billing. Rotation and recovery invalidate both previous credentials without resetting usage.