What this request does
The TSV list validation request sends an email list to ListCleaner as multipart form data. It is intended for CRM exports, newsletter databases, lead files and other structured datasets that contain one column of email addresses. The API preserves the uploaded dataset for the cleaning workflow while the mapping field identifies which column should be validated.
TSV input uses tab characters between fields and should include a header row. A successful upload returns a list UID. Store that UID with your own job record because it is the stable reference used to inspect processing status and download the cleaned results. Uploading creates an asynchronous job: the initial response confirms acceptance, not completion.
How to use /upload_list
Export a valid TSV file and make sure the email column has a recognizable header.
Send the file, the email mapping value and an optional human-readable reference.
Poll the list-status endpoint and download results only after processing has completed.
Headers, parameters and fields
| Name | Location | Required | Description |
|---|---|---|---|
X-User-Email | Header | Yes | Email address belonging to the ListCleaner API account. |
X-Api-Key | Header | Yes | Secret API key for the authenticated ListCleaner account. |
file | Multipart body | Yes | TSV file containing the email list. Maximum 100 MB and 1,000,000 data rows. |
mapping | Multipart body | Yes | Email column header. The example uses email. |
reference | Multipart body | No | A label such as a campaign, source or month that helps identify the job later. |
delimiter | Multipart body | Recommended | Set this to tab so the file is interpreted with the intended separator. |
Response behavior
- The response confirms that the job was created.
- The uid value identifies the list in later status and download calls.
- records_total reports the accepted data-row count when available.
Execute this request
Edit the request values, then send a live authenticated request to ListCleaner. The HTTP status and duration appear in the response bar, with the actual API response body directly below. File endpoints provide a download link instead of printing binary data.
The live API response will appear here.
Code examples in 10 languages
After credentials are entered above, every example includes the actual account email and API key so the copied request can run immediately. Clear the credentials to return to placeholders.
Use cases and best practices
Common use cases
- Validate a TSV export before importing it into an email platform.
- Clean CRM contacts before a migration or re-engagement campaign.
- Automate recurring list-quality checks from a backend data pipeline.
Recommended implementation practices
- Upload from a trusted backend instead of exposing API credentials in browser code.
- Retain the returned UID and your own reference together.
- Do not treat upload acceptance as cleaning completion.
- Validate the file structure before consuming credits on a large production upload.
Upload a TSV email list questions
Answers to common implementation, security and response-handling questions for this specific request.
How should the email column be selected for a TSV file?
Use the exact header and set delimiter=tab so tab-separated content is interpreted consistently. The mapping value must resolve to the column that contains the addresses to clean.
What happens after the TSV upload succeeds?
ListCleaner creates an asynchronous cleaning job and returns its UID. Use the status request to follow the job before requesting result files.
Can I upload a TSV file directly from frontend JavaScript?
The API accepts the request, but production integrations should proxy uploads through a trusted backend so the API key is not exposed to website visitors.
What are the bulk upload limits?
The documented limit is 100 MB and up to 1,000,000 data rows per upload. Validate limits and file structure before submission.