API
Listcleaner API Documentation
Our Email list cleaning API is easy to use and integrates within any software language.
Here you can find our email list cleaning API documentation, with ready made Java examples.
Getting started
Your API key
You can retrieve and renew your API key by clicking on the "API KEY" button, on the Listcleaner dashboard.
Click here to go to your dashboard.
Click here to go to your dashboard.
Your Username
Your username is the same as your account's email address
API Request parameters
Every request to our List Cleaning API requires these header parameters:
X-User-Email string
X-Api-Key string
Depending on the API call other query parameters are:
uid string This uid is the identifier of an uploaded data file.
file string($binary) The comma separated CSV file to be uploaded
mapping string The column name of your CSV file containing the email adresses
reference string Reference for your datafile
export_type string Choose options: all, ok, bad, for the requested dataset download.
API Response codes
Every response from our List Cleaning API come with a response code
200 Success
401 Unauthorized (check your username and API key)
400 Missing UID or other request error (check if the UID is in the request)
404 File not found (File not found or not ready for download)
404 File not found (File not found or not ready for download)
Listcleaner API request examples
Listcleaner API - Java examples
Java
/get_credits
Retrieve the amount of available credits
Request:
Java
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class GetCredits {
public static void main(String[] args) {
try {
// Define the URL for the API request
URL url = new URL("https://api.listcleaner.net/get_credits");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// Set the HTTP request method to GET
connection.setRequestMethod("GET");
// Set the required headers
connection.setRequestProperty("accept", "application/json");
connection.setRequestProperty("X-User-Email", "username@domain.com");
connection.setRequestProperty("X-Api-Key", "YOUR_API_KEY");
// Get the response code to check if the request was successful
int responseCode = connection.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) { // 200 status code
// Read and display the response
BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
String inputLine;
StringBuffer content = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
content.append(inputLine);
}
// Close the stream
in.close();
// Output the response
System.out.println("Response: " + content.toString());
} else {
System.out.println("GET request failed. Response code: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Response (code 200):
vim
{
"credits": 0
}
Java
/upload_list
Upload your email data file to be cleaned
Request:
Java
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
public class UploadList {
public static void main(String[] args) {
String url = "https://api.listcleaner.net/upload_list";
String charset = "UTF-8";
String filePath = "YOUR_FILENAME.csv";
String mapping = "YOUR_MAPPING_COLUMN";
String reference = "YOUR_REFERENCE";
String boundary = Long.toHexString(System.currentTimeMillis()); // Just generate some unique boundary
String lineFeed = "\r\n";
try {
// Open a connection to the URL
HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
connection.setDoOutput(true);
connection.setRequestMethod("POST");
connection.setRequestProperty("accept", "application/json");
connection.setRequestProperty("X-User-Email", "username@domain.com");
connection.setRequestProperty("X-Api-Key", "YOUR_API_KEY");
connection.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
try (
OutputStream output = connection.getOutputStream();
PrintWriter writer = new PrintWriter(new OutputStreamWriter(output, charset), true)
) {
// Send file part
File file = new File(filePath);
writer.append("--").append(boundary).append(lineFeed);
writer.append("Content-Disposition: form-data; name=\"file\"; filename=\"").append(file.getName()).append("\"").append(lineFeed);
writer.append("Content-Type: text/csv").append(lineFeed); // Adjust this based on the file type
writer.append(lineFeed).flush();
try (InputStream inputStream = new FileInputStream(file)) {
byte[] buffer = new byte[1024];
for (int length; (length = inputStream.read(buffer)) > 0; ) {
output.write(buffer, 0, length);
}
output.flush();
}
writer.append(lineFeed).flush();
// Send mapping part
writer.append("--").append(boundary).append(lineFeed);
writer.append("Content-Disposition: form-data; name=\"mapping\"").append(lineFeed);
writer.append("Content-Type: text/plain; charset=").append(charset).append(lineFeed);
writer.append(lineFeed).append(mapping).append(lineFeed).flush();
// Send reference part
writer.append("--").append(boundary).append(lineFeed);
writer.append("Content-Disposition: form-data; name=\"reference\"").append(lineFeed);
writer.append("Content-Type: text/plain; charset=").append(charset).append(lineFeed);
writer.append(lineFeed).append(reference).append(lineFeed).flush();
// End of multipart request
writer.append("--").append(boundary).append("--").append(lineFeed).flush();
}
// Get response
int responseCode = connection.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) {
try (BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
String responseLine;
StringBuilder response = new StringBuilder();
while ((responseLine = reader.readLine()) != null) {
response.append(responseLine).append("\n");
}
System.out.println("Response: " + response.toString());
}
} else {
System.out.println("Error: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Response (code 200):
vim
{
"status": "File uploaded successfully",
"uid": "d53dec-bac2b5-34dfd1",
"records_total": 28391
}
Java
/show_lists
Have a look at all your lists
?uid is optional and will only show that specific list.
Request:
Java
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class ShowLists {
public static void main(String[] args) {
// Optional uid parameter
String uid = "abc123-def456-ghi789";
String urlString = "https://api.listcleaner.net/show_lists?uid=" + uid;
try {
// Create a URL object
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// Set the HTTP request method to GET
connection.setRequestMethod("GET");
// Set the required headers
connection.setRequestProperty("accept", "application/json");
connection.setRequestProperty("X-User-Email", "username@domain.com");
connection.setRequestProperty("X-Api-Key", "YOUR_API_KEY");
// Get the response code to check if the request was successful
int responseCode = connection.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) { // 200 status code
// Read and display the response
BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
String inputLine;
StringBuilder content = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
content.append(inputLine);
}
// Close the stream
in.close();
// Output the response
System.out.println("Response: " + content.toString());
} else {
System.out.println("GET request failed. Response code: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Response (code 200):
vim
{
"lists": [
{
"uid": "abc123-def456-ghi789",
"created": "2024-01-01 00:00:01",
"filename_original": "dummy.csv",
"reference": "Dummy File Upload",
"mapping": "emailaddress",
"records_total": 436,
"records_processed": "436",
"records_ok": "405",
"records_bad": "31",
"records_bad_breakdown": "{\"catch_all\": 2, \"blacklisted_email\": 1, \"spamtrap\": 1, \"account_inactive\": 4, \"syntax_error\": 1, \"mx_server_offline\": 1, \"invalid_mx\": 3, \"disposable_domain\": 16, \"mx_server_error\": 2}",
"paid": "paid",
"current_step": "done",
"current_status": "done",
"last_status_update": "2024-01-01 00:01:02"
}
]
}
Java
/download_list
Download your cleaned lists, when its current_status is "done".
Options:
all -> Export of all the data
ok -> Export of the clean data
bad -> Export of the bad data
The statuses can be found in the "reason" column.
(We use "abc123-def456-ghi789" as example uid.)
Request:
Java
import java.io.BufferedInputStream;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
public class DownloadList {
public static void main(String[] args) {
// Parameters
String uid = "abc123-def456-ghi789";
String exportType = "all";
String urlString = "https://api.listcleaner.net/download_list?uid=" + uid + "&export_type=" + exportType;
try {
// Create a URL object
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// Set the HTTP request method to GET
connection.setRequestMethod("GET");
// Set the required headers
connection.setRequestProperty("accept", "*/*");
connection.setRequestProperty("X-User-Email", "username@domain.com");
connection.setRequestProperty("X-Api-Key", "YOUR_API_KEY");
// Get the response code to check if the request was successful
int responseCode = connection.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) { // 200 status code
// Save the response to a file
InputStream in = new BufferedInputStream(connection.getInputStream());
FileOutputStream fileOutputStream = new FileOutputStream("downloaded_list.csv");
byte[] dataBuffer = new byte[1024];
int bytesRead;
while ((bytesRead = in.read(dataBuffer, 0, dataBuffer.length)) != -1) {
fileOutputStream.write(dataBuffer, 0, bytesRead);
}
// Close the streams
fileOutputStream.close();
in.close();
System.out.println("List downloaded successfully.");
} else {
System.out.println("GET request failed. Response code: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Java
/delete_list
Remove your list from the panel
Request:
Java
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class DeleteList {
public static void main(String[] args) {
// Parameters
String uid = "abc123-def456-ghi789";
String urlString = "https://api.listcleaner.net/delete_list?uid=" + uid;
try {
// Create a URL object
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// Set the HTTP request method to POST
connection.setRequestMethod("POST");
// Set the required headers
connection.setRequestProperty("accept", "*/*");
connection.setRequestProperty("X-User-Email", "username@domain.com");
connection.setRequestProperty("X-Api-Key", "YOUR_API_KEY");
// Optional: Send an empty body
connection.setDoOutput(true);
connection.getOutputStream().write("".getBytes());
// Get the response code to check if the request was successful
int responseCode = connection.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) { // 200 status code
// Read and display the response
BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
String inputLine;
StringBuilder content = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
content.append(inputLine);
}
// Close the stream
in.close();
// Output the response
System.out.println("Response: " + content.toString());
} else {
System.out.println("POST request failed. Response code: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Response (code 200):
vim
{
"status": "List removed successfully"
}
