Bulk Email Validation AI Agent / LLM
UtilitiesEverything an AI coding assistant needs to write a working Bulk Email Validation integration without opening another page: endpoint, authentication, parameters, a real request, both response shapes and the platform rules it cannot infer from a single example. Copy the brief below and paste it into Claude, Cursor, GitHub Copilot, ChatGPT or any other agent.
Machine-readable spec — Markdown
# Bulk Email Validation API — Way2API® - **Endpoint:** `POST https://app.way2api.com/api/v1/email/validate/bulk` - **Auth:** `Authorization: Bearer YOUR_API_KEY` (or `X-API-Key: YOUR_API_KEY`) - **Content-Type:** `application/json` - **Category:** Utilities - **Availability:** Available worldwide - **Docs:** https://app.way2api.com/documentation/email-validation-bulk ## What it does Bulk Email Validation API — the same deliverability check as Email Validation, for up to 100 addresses in a single billable call. Every entry in results has exactly the shape a single-address lookup returns, so one parser handles both endpoints. Duplicate addresses are collapsed before the lookup, and total_requested versus total_returned lets you detect a short response. Built for cleaning imported lists, validating CSV uploads and periodic re-verification of a mailing database. ## Request body (application/json) | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `emails` | array | yes | Array of 1–100 email addresses to validate, e.g. ["[email protected]", "[email protected]"]. Duplicates are removed. | ## Example request ```bash curl -X POST https://app.way2api.com/api/v1/email/validate/bulk \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"emails":["[email protected]","not-an-email"]}' ``` ## Success response — 200 ```json { "status": "SUCCESS", "status_code": 200, "charged": true, "success": true, "message": "", "message_code": "OK", "order_id": "W2A1739512345abcdef01", "data": { "order_id": "W2A1739512345abcdef01", "result": { "total_requested": 3, "total_returned": 3, "results": [ { "email": "[email protected]", "result": "valid", "is_valid": true, "is_syntax_valid": true, "reason": "", "domain": { "name": "example.com", "is_valid": true, "is_disposable": false, "is_free": false, "is_spam": false, "is_catch_all": false }, "account": { "is_role": false, "is_full_mailbox": false }, "mx_records": [ "mx1.example.com.", "mx2.example.com.", "mx3.example.com.", "mx4.example.com.", "mx5.example.com." ] }, { "email": "not-an-email", "result": "invalid_syntax", "is_valid": false, "is_syntax_valid": false, "reason": "", "domain": { "name": "not-an-email", "is_valid": false, "is_disposable": false, "is_free": false, "is_spam": false, "is_catch_all": false }, "account": { "is_role": false, "is_full_mailbox": false }, "mx_records": [] }, { "email": "[email protected]", "result": "invalid", "is_valid": false, "is_syntax_valid": true, "reason": "mx record does not exist.", "domain": { "name": "nonexistentdomainxyz123abc.com", "is_valid": false, "is_disposable": false, "is_free": false, "is_spam": false, "is_catch_all": false }, "account": { "is_role": false, "is_full_mailbox": false }, "mx_records": [] } ] } } } ``` ## Error response — 400 ```json { "status": "FAILED", "status_code": 400, "charged": false, "success": false, "message": "Please provide data in required format in request body", "message_code": "REQUEST_FAILED", "order_id": "W2A1739512345abcdef01", "data": { "order_id": "W2A1739512345abcdef01", "error_code": "Invalid request body Exception" } } ``` ## Integration rules - Every response is JSON carrying `status`, `status_code`, `charged`, `success`, `message`, `message_code` and (once a call reaches the provider) `order_id`. The verification payload is under `data.result`. - `charged` (boolean) is the authority on billing. Do NOT infer it from the HTTP status: `422` is returned both for input we rejected (not charged) and for a lookup the provider ran and billed us for that returned a negative result (charged). - `message_code` is a fixed vocabulary — branch on it instead of parsing `message`. Values: `OK`, `ACCEPTED`, `PROVIDER_NO_RESPONSE`, `VERIFICATION_FAILED`, `NO_RECORD_FOUND`, `INVALID_INPUT`, `REQUEST_FAILED`, `MISSING_API_KEY`, `INVALID_API_KEY`, `INSUFFICIENT_BALANCE`, `NO_API_ACCESS`, `NOT_FOUND`, `RATE_LIMITED`, `INTERNAL_ERROR`, `PROVIDER_UNAVAILABLE`. - `success` reports the verification outcome; `status` reports the ORDER lifecycle (`SUCCESS`/`PENDING`/`FAILED`). They differ on a charged negative result: the order completed and was billed while the verification did not pass. - A failed verification is still a successful HTTP call — the outcome lives in the response body, so do not treat `200` as "verified". - Status codes: `200` result returned, `202` pending or provider did not respond (both charged — quote the `order_id`), `401` missing/invalid key, `402` insufficient balance, `403` no access to this service, `422` see `charged`, `429` rate limited (honour the `Retry-After` header), `503` temporarily unavailable. - Rate limits are per API key, per service, on a 1-minute sliding window. - Load the API key from an environment variable or secret store. Never hard-code it, never commit it, and never ship it in client-side code — calls must be made from your backend.
Prompts to pair it with
- Write a production-ready Bulk Email Validation integration in PHP using this spec, with error handling and retries.
- Given this spec, generate typed request/response models and a client class.
- Review my existing Bulk Email Validation integration against this spec and list what I handle incorrectly.
⚠ Before you paste generated code
Never let an assistant hard-code your API key — load it from an environment variable or a
secret store, and call this endpoint from your backend only. A failed verification is still a
successful HTTP call, so check the success field in the body
rather than treating 200 as verified.