What this request does
The delimited TXT 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.
Text files must be consistently delimited; the example uses a pipe separator. 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 delimited TXT 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 | delimited TXT 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 pipe 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 delimited TXT 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 delimited TXT 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 delimited TXT file?
Use the exact header and provide comma, semicolon, tab or pipe as the delimiter when automatic detection is not appropriate. The mapping value must resolve to the column that contains the addresses to clean.
What happens after the delimited TXT 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 delimited TXT 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.