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 C# (.NET) 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 - C# (.NET) examples
C#
/get_credits
Retrieve the amount of available credits
Request:
C#
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly HttpClient client = new HttpClient();
static async Task Main(string[] args)
{
// Set up the request URL
string url = "https://api.listcleaner.net/get_credits";
// Set the headers
client.DefaultRequestHeaders.Add("accept", "application/json");
client.DefaultRequestHeaders.Add("X-User-Email", "username@domain.com");
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
try
{
// Send the GET request
HttpResponseMessage response = await client.GetAsync(url);
// Check if the request was successful
if (response.IsSuccessStatusCode)
{
// Read the response body as a string
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine("Response: " + responseBody); // Output user credits
}
else
{
Console.WriteLine($"Request failed with status code: {response.StatusCode}");
}
}
catch (HttpRequestException e)
{
Console.WriteLine($"Request error: {e.Message}");
}
}
}
Response (code 200):
vim
{
"credits": 0
}
C#
/upload_list
Upload your email data file to be cleaned
Request:
C#
using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly HttpClient client = new HttpClient();
static async Task Main(string[] args)
{
string url = "https://api.listcleaner.net/upload_list";
// Set the headers
client.DefaultRequestHeaders.Add("accept", "application/json");
client.DefaultRequestHeaders.Add("X-User-Email", "username@domain.com");
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
using (var form = new MultipartFormDataContent())
{
// Add the file content
var fileStream = new FileStream("YOUR_FILENAME.csv", FileMode.Open);
form.Add(new StreamContent(fileStream) { Headers = { ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("text/csv") } }, "file", "YOUR_FILENAME.csv");
// Add additional fields
form.Add(new StringContent("YOUR_MAPPING_COLUMN"), "mapping");
form.Add(new StringContent("YOUR_REFERENCE"), "reference");
try
{
// Send the POST request
var response = await client.PostAsync(url, form);
response.EnsureSuccessStatusCode();
// Read and output the response
var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine("Response: " + responseBody);
}
catch (HttpRequestException e)
{
Console.WriteLine($"Request error: {e.Message}");
}
}
}
}
Response (code 200):
vim
{
"status": "File uploaded successfully",
"uid": "d53dec-bac2b5-34dfd1",
"records_total": 28391
}
C#
/show_lists
Have a look at all your lists
?uid is optional and will only show that specific list.
Request:
C#
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly HttpClient client = new HttpClient();
static async Task Main(string[] args)
{
// Optional uid parameter
string uid = "abc123-def456-ghi789";
string url = $"https://api.listcleaner.net/show_lists?uid={uid}";
client.DefaultRequestHeaders.Add("accept", "application/json");
client.DefaultRequestHeaders.Add("X-User-Email", "username@domain.com");
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
try
{
// Send the GET request
HttpResponseMessage response = await client.GetAsync(url);
// Check if the request was successful
if (response.IsSuccessStatusCode)
{
// Read the response body as a string
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine("Response: " + responseBody); // Output the response
}
else
{
Console.WriteLine($"Request failed with status code: {response.StatusCode}");
}
}
catch (HttpRequestException e)
{
Console.WriteLine($"Request error: {e.Message}");
}
}
}
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"
}
]
}
C#
/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:
C#
using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly HttpClient client = new HttpClient();
static async Task Main(string[] args)
{
// Parameters
string uid = "abc123-def456-ghi789";
string exportType = "all";
string url = $"https://api.listcleaner.net/download_list?uid={uid}&export_type={exportType}";
client.DefaultRequestHeaders.Add("accept", "*/*");
client.DefaultRequestHeaders.Add("X-User-Email", "username@domain.com");
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
try
{
var response = await client.GetAsync(url);
response.EnsureSuccessStatusCode(); // Throw if not a success code.
var content = await response.Content.ReadAsByteArrayAsync();
await File.WriteAllBytesAsync("downloaded_list.csv", content);
Console.WriteLine("List downloaded successfully.");
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
}
}
C#
/delete_list
Remove your list from the panel
Request:
C#
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly HttpClient client = new HttpClient();
static async Task Main(string[] args)
{
// Parameters
string uid = "abc123-def456-ghi789";
string url = $"https://api.listcleaner.net/delete_list?uid={uid}";
// Create the request
var request = new HttpRequestMessage(HttpMethod.Post, url);
request.Headers.Add("accept", "*/*");
request.Headers.Add("X-User-Email", "username@domain.com");
request.Headers.Add("X-Api-Key", "YOUR_API_KEY");
// Send the request
HttpResponseMessage response = await client.SendAsync(request);
if (response.IsSuccessStatusCode)
{
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Response: {responseBody}"); // Output the response
}
else
{
Console.WriteLine($"Error: {response.StatusCode}");
}
}
}
Response (code 200):
vim
{
"status": "List removed successfully"
}
