ListClean

Delete one email list and its verification results, via DELETE /lists/{list_id}. THE ONLY DESTRUCTIVE TOOL ON THIS PROVIDER, and it is permanent: ListClean publishes no recycle bin, no undelete and no trashed state -- the contract's only list states are `SUBMITTED`, `INPROCESS` and `COMPLETED` -- so the verified results go with the record and re-verifying those addresses spends the credits again. The reply is the envelope with a `message` ("Lists deleted successfully") and NO `data`, so it says nothing about what was removed; confirm by asking for the list again or by listing lists. `list_id` is refused unless it is a plain integer -- a DELETE whose path argument can change which endpoint it reaches is the worst place on this surface for an unguarded value. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

Read the ListClean account's own profile and billing contact details, via GET /account/profile. `data` carries `name`, `address`, `city`, `country`, `phone_number`, `skype_id`, `company_name`, `website`, `twitter_handle`, `linkedin` and the three `billing_*` fields. THIS IS THE SUBSCRIPTION'S OWN PROFILE, not a contact record: an agent that mistakes it for a CRM entry is reading the customer's own billing details. The contract's documented 200 lists those thirteen fields and no credential -- but that is the vendor's document rather than a measurement, and no ListClean key existed for this build to look at a live reply, so whether this endpoint returns anything credential-shaped is UNKNOWN rather than answered. The trailing slash is not load-bearing here either (measured 2026-09-25: `/account/profile` and `/account/profile/` answer identically). Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

Read how many verification credits the ListClean account has left, via GET /credits. `data.credits` is the remaining balance. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. THIS IS ALSO THE CONNECTION'S HEALTH CHECK, and it is the endpoint the provider's credential declaration names: it is read-only and spends nothing, which is why it rather than a verification was chosen. ListClean meters verification by credit (its single-verification log records `credits_deducted`, normally 1 per address), so read 'Get remaining verification credits' before a bulk run rather than after. MEASURED 2026-09-25, and the reason this provider's key is stored UNVERIFIED rather than checked at the paste box: a bogus `X-Auth-Token`, an `Authorization: Bearer` value and no credential at all all answer 401 with the identical body `{"success":0,"error_code":0,"message":"Invalid token or token expired"}`, so this endpoint cannot tell a rejected key from an absent one, and no 200 has ever been observed on this provider.

Read one list's verified addresses of a given quality as JSON, via GET /downloads/json/{list_id}/{type}. THIS IS HOW THE VERDICTS COME BACK from a batch verification or a CSV upload. `type` selects the bucket -- `clean`, `dirty` or `unknown` -- and there is no 'all', so three calls read a whole list. Useful only once 'Get one email list' reports `status: COMPLETED`. The contract publishes no response schema for this route, so the reply's exact shape is unrecorded and no 200 has been observed. THE CSV SIBLING IS NOT SHIPPED: `GET /downloads/{list_id}/{type}` is the same data as a downloadable file (the vendor: "Download lists results as a csv file", answering a stream of octets), and this platform carries binary downloads only through a bounded artifact-transport contract this integration does not have, so it is emitted on no surface and refused by name if its id is guessed. Nothing is unreachable: this route addresses the identical three buckets of the identical list. THE CONTRACT ALSO DECLARES AN OPTIONAL `X-Auth-Token` QUERY PARAMETER ON THIS ROUTE AND IT IS DELIBERATELY ABSENT FROM THIS SCHEMA: that is the account's API key, the platform attaches the credential itself, and an argument that could set it would let a caller push their own key through this integration or put a live secret in a URL where access logs keep it.

List this account's email lists with their verification analytics, via GET /lists. `data` IS AN OBJECT HERE -- `total`, `cursor` and `lists[]` -- and each row carries `list_id`, `filename`, `size_in_bytes`, `request_time`, a `status` of `SUBMITTED`, `INPROCESS` or `COMPLETED`, a STRING `upload_id`, an `analytics` block (totals, duplicates, clean and dirty counts with percentages, and per-category breakdowns such as "Disposable Email" or "High Quality") and a `cost` block in INR and USD. THE CURSOR IS ADVERTISED AND UNREACHABLE: `data.cursor` comes back in the reply while the contract declares NO query parameter on this route, so there is no documented way to ask for the next page. If an account holds more lists than one call returns, this build cannot page them; that needed a live account to settle and is recorded rather than guessed. Note the shape difference from 'Get one email list', which returns `data[]` directly. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

Read one list's status, analytics and cost, via GET /lists/{list_id}. The same per-list record 'List email lists' returns -- `filename`, `size_in_bytes`, `request_time`, `status`, `analytics` and `cost` -- BUT `data` IS AN ARRAY HERE, not an object: the listing wraps its rows in `data.lists[]` while this route returns `data[]` directly, as a one-element array. Read `data[0]`. THIS IS THE ROUTE TO POLL after 'Verify a batch of email addresses' or after a CSV upload finishes: `status` moves `SUBMITTED` -> `INPROCESS` -> `COMPLETED`, and the verdicts become readable with 'Get a list's verification results' once it is `COMPLETED`. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

List the chunked CSV uploads this account has started, via GET /uploads. Each entry is an `upload_id`, a `status` (contract example "COMPLETED") and a `progress` percentage. AN UPLOAD IS NOT A LIST: an upload is the file TRANSFER, and the verified list it produces is read with 'List email lists' -- see 'Get a CSV upload's status' for why the two id spaces cannot be assumed to match. THE TRAILING SLASH IS NOT LOAD-BEARING: the contract spells this route `/uploads/` and the research ledger `/uploads`; measured 2026-09-25 both answer identically for GET and POST (401 to a bogus key, where a path that does not exist answers 404 with an HTML error page), so this build ships the slash-less form. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

Read how far a chunked CSV upload has got, via GET /uploads/{upload_id}. `data.status` is `inprocess`, `success` or `error`; `data.progress` is a completion percentage; and `data.chunk_details` gives `total_chunk_count` beside `uploaded_chunk_count`, which is how you tell which chunks still have to be sent. Poll here between chunks and after the last one. THE THREE ID SPACES DO NOT LINE UP AND THIS BUILD DOES NOT GUESS: 'List CSV uploads' returns an INTEGER `upload_id` (contract example 1327), this route returns an integer `request_id` (example 312), and 'List email lists' returns an integer `list_id` (example 1) beside a STRING `upload_id` (example "Q1636218416-991025"). One field name, two types, and nothing in the contract says which maps to which -- so read the value out of the reply in hand rather than assuming one is another. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

Verify a single email address and read its deliverability verdict, via GET /verify/email/{email}. `data.status` is `clean`, `dirty`, `unknown` or `error`, with `data.remarks` saying why (the contract's examples are "Email does not exists" and "Disposable Email"), beside `disposable`, `role_based`, `free_email`, `mx_found`, `mx_records`, `msp` (the mailbox provider, e.g. GMAIL) and the address split into `email_user` and `email_domain`. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. ListClean meters verification by credit (its single-verification log records `credits_deducted`, normally 1 per address), so read 'Get remaining verification credits' before a bulk run rather than after. FOR MORE THAN A HANDFUL OF ADDRESSES use 'Verify a batch of email addresses' instead -- this route is one call and one credit per address. THE ADDRESS IS A PATH SEGMENT, so the connector refuses a value carrying `/`, `?`, `#`, `\`, a `..` dot segment or a control character rather than sending it. That turns away a handful of syntactically legal addresses (RFC 5322 allows `/` and `?` in a local part) and it costs nothing real: measured 2026-09-25, `%2F` in this position answers 404 from ListClean's web server before the application sees it, so such an address cannot be verified through this route at all. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

Read the log of single-address verifications this account has run, via GET /verify/email/logs. One entry per 'Verify one email address' call: `id`, `entered` (the timestamp), `email`, `status`, `remarks`, `credits_deducted` and `error_code`. THIS IS WHERE THE CREDIT COST IS VISIBLE per verification. It covers the SINGLE-ADDRESS route only -- batch verifications and CSV uploads become lists instead, and are read with 'List email lists'. NO PAGINATION IS DOCUMENTED: the contract declares no query parameter on this route and the reply carries no cursor, so one call returns whatever it returns. Whether that is the whole log or a truncation could not be measured without a ListClean credential. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

Change the ListClean account's profile and billing contact details, via POST /account/profile. THE WIDEST WRITE ON THIS SURFACE, and it edits the SUBSCRIPTION rather than any customer record: the name, company, address, website and billing details on the ListClean account itself. Not marked destructive -- nothing is deleted -- but a careless call here rewrites the invoice contact. Every member is optional and whether an omitted one is preserved could not be measured, so send only what you mean to change. THE BODY IS CHECKED BEFORE THE CREDENTIAL ON THIS ONE ROUTE, measured 2026-09-25 and true nowhere else on this provider: no body answers 400 "No body provided", `{}` answers 400 "Body not in proper json format", and only a body with a real member reaches the credential and answers 401. So a 400 from this tool is about what you sent, never about the connection. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

Open a chunked CSV upload and get the `upload_id` its chunks are sent under, via POST /uploads. STEP ONE OF THREE, AND IT CARRIES NO FILE CONTENT -- it reserves the upload and returns `data.upload_id`. Then send each chunk with 'Send one chunk of a CSV upload' and watch 'Get a CSV upload's status'. `filename`, `file_type`, `total_chunk_count` and `max_chunk_size` are all required, which means THE SPLIT IS DECIDED BEFORE THE UPLOAD IS OPENED: the chunk count is declared here, not discovered later. `fast_process` is the option with consequences -- 1 skips SMTP probing and verifies from cache, DNS and format only, which is faster and less certain than the default 0. ListClean meters verification by credit (its single-verification log records `credits_deducted`, normally 1 per address), so read 'Get remaining verification credits' before a bulk run rather than after. Every address in the file costs one. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

Send one base64-encoded chunk of a CSV file to an open upload, via POST /uploads/{upload_id}. STEP TWO OF THREE. `chunk_sequence_number` and `content` are required; `content` is the chunk's bytes BASE64-ENCODED, and `md5_checksum` is the optional hash ListClean uses to check the chunk arrived intact -- send it. Chunks are addressed by sequence number, so one can be re-sent, and 'Get a CSV upload's status' reports `uploaded_chunk_count` against the total declared when the upload was opened. THIS IS THE ONE TOOL ON THIS PROVIDER THAT CARRIES BULK DATA IN AN ARGUMENT: a chunk is a base64 string in a JSON body, base64 inflates the bytes by about a third, and `max_chunk_size` was declared in bytes of the RAW slice rather than of this string. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.

Submit up to 3,000 addresses for verification and receive the list id their results will appear under, via POST /verify/email/batch. ASYNCHRONOUS, AND IT RETURNS NO VERDICTS. The reply carries `data[].list_id` -- a LIST id, the same identifier 'List email lists' and 'Get one email list' use -- and the addresses are verified afterwards. Poll 'Get one email list' until its `status` reaches `COMPLETED` (the other values are `SUBMITTED` and `INPROCESS`), then read the verdicts with 'Get a list's verification results'. An agent that reads this reply expecting statuses will find an id and conclude the call failed. ListClean meters verification by credit (its single-verification log records `credits_deducted`, normally 1 per address), so read 'Get remaining verification credits' before a bulk run rather than after. Like every reply on this API it is an envelope: `success` (1 or 0, an INTEGER and not a boolean), a human `message`, usually an `error_code`, and the payload under `data`. The success shape here is the vendor's published contract, not a measured reply: no ListClean credential existed for this build, so no 200 on this provider has been observed.