AI Scoring API

The ZeroBounce AI Scoring API combines a vast selection of data with proven statistical analysis to granularly rate the quality level of an email address. The software identifies positive and negative patterns of an email address and returns a score that users can rely on when performing their email hygiene. The methodology of ZeroBounce A.I. periodically adjusts as email trends evolve.

Get an in-depth look into the quality of your leads by learning more about your subscribers’ online activity. With the added information you can segment your lists to better serve your customers with targeted messaging. If you want to further segment your email list based on Quality Score, we recommend validating your "valid" file also.

AI Scoring API: Send File

/ai-scoring-api/send-file/

The scoring sendfile API allows a user to send a file for bulk email scoring. The content type needs to be multipart/form-data. Please refer to the C# example for details.

POST /V2/SCORING/SENDFILE

API URL: https://bulkapi.zerobounce.net/v2/scoring/sendfile

URL Parameters

  • Parameter
    Required/Optional
    Description
  • file
    Required
    The csv or txt file. Byte array contents for the submitted file. The content's header is type of "text/csv"
  • api_key
    Required
    Your API Key, found in your account
  • email_address_column
    Required
    The column index of the email address in the file. Index starts at 1
  • return_url
    Optional
    The URL will be used as a callback when the scoring service is completed
  • has_header_row
    Optional
    If the first row from the submitted file is a header row. True or False

Send File Code Samples

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
  • Android Java
      
' Send File Sample in VB.net

Public Class SendFileStatus
   Public Property success As Boolean
   Public Property message As String
   Public Property file_name As String
   Public Property file_id As String
End Class

Private Shared Sub SendFileAPITest()
   Dim fileFullPath As String = $"full file path of a csv or txt file"  ' required
   Dim apiKey As String = "replace with your api key here"              ' required
   Dim emailAddressColumn As Integer = 2  ' required
   Dim ipAddressColumn As Integer? = 11   ' optional
   Dim hasHeaderRow As Boolean? = True    ' optional
   Dim returnUrl As String = Nothing      ' optional

   Try
       Dim sendFileStatus As SendFileStatus = SendFile(fileFullPath, apiKey, emailAddressColumn, ipAddressColumn, hasHeaderRow, returnUrl).Result
       Console.Write(JsonConvert.SerializeObject(sendFileStatus, Formatting.Indented))
   Catch ex As Exception
       Console.Write(ex.InnerException.Message)
   End Try

   Console.ReadKey()
End Sub

Public Shared Async Function SendFile(ByVal fileFullPath As String, 
                                     ByVal apiKey As String, 
                                     ByVal emailAddressColumn As Integer, 
                                     ByVal Optional ipAddressColumn As Integer? = Nothing, 
                                     ByVal Optional hasHeaderRow As Boolean? = Nothing, 
                                     ByVal Optional returnUrl As String = Nothing) As Task(Of SendFileStatus)

   If String.IsNullOrEmpty(fileFullPath) Then Throw New Exception("Error: fileFullPath is required")
   If String.IsNullOrEmpty(apiKey) Then Throw New Exception("Error: apiKey is required")
   Dim fi = New FileInfo(fileFullPath)
   Dim fileContents = File.ReadAllBytes(fi.FullName)
   Dim fileName = fi.Name
   Dim uri As Uri = New Uri("https://bulkapi.zerobounce.net/v2/scoring/sendfile")

   Using client = New HttpClient()

       Using request = New HttpRequestMessage(HttpMethod.Post, uri)
           Dim multiPartContent As MultipartFormDataContent = New MultipartFormDataContent()
           Dim byteArrayContent As ByteArrayContent = New ByteArrayContent(fileContents)
           byteArrayContent.Headers.Add("Content-Type", "text/csv")
           multiPartContent.Add(byteArrayContent, "file", fileName)
           multiPartContent.Add(New StringContent(apiKey), "api_key")
           multiPartContent.Add(New StringContent(emailAddressColumn.ToString()), "email_address_column")
           If ipAddressColumn IsNot Nothing Then multiPartContent.Add(New StringContent(ipAddressColumn.ToString()), "ip_address_column")
           If hasHeaderRow IsNot Nothing Then multiPartContent.Add(New StringContent(If((hasHeaderRow = True), "true", "false")), "has_header_row")
           If returnUrl IsNot Nothing Then multiPartContent.Add(New StringContent(returnUrl.ToString()), "return_url")
           request.Content = multiPartContent

           Using response = Await client.SendAsync(request, HttpCompletionOption.ResponseContentRead, CancellationToken.None).ConfigureAwait(False)
               Dim content = Await response.Content.ReadAsStringAsync()

               If response.IsSuccessStatusCode = False Then
                   Dim error As String = $"StatusCode = {CInt(response.StatusCode)}, Content = {content}"
                   Throw New Exception(error)
               End If

               Return JsonConvert.DeserializeObject(Of SendFileStatus)(content)
           End Using
       End Using
   End Using
End Function
   

// Send File Sample in C#

public class SendFileStatus
{
   public bool success { get; set; }
   public string message { get; set; }
   public string file_name { get; set; }
   public string file_id { get; set; }
}

private static void SendFileAPITest()
{
   string fileFullPath = $"full file path of a csv or txt file";  //required
   string apiKey = "replace with your api key here";  //required       
   int emailAddressColumn = 2;  //required
   int? ipAddressColumn = 11;  //optional
   bool? hasHeaderRow = true;  //optional
   string returnUrl = null;  //optional

   try
   {
       SendFileStatus sendFileStatus = SendFile(fileFullPath, apiKey, emailAddressColumn, ipAddressColumn, hasHeaderRow, returnUrl).Result;
       Console.Write(JsonConvert.SerializeObject(sendFileStatus, Formatting.Indented));
   }
   catch (Exception ex)
   {
       Console.Write(ex.InnerException.Message);
   }

   Console.ReadKey();
}

public static async Task<SendFileStatus> SendFile(string fileFullPath, string apiKey, int emailAddressColumn, 
                                           int? ipAddressColumn = null, bool? hasHeaderRow = null, string returnUrl = null)
{
   if (string.IsNullOrEmpty(fileFullPath))
       throw new Exception("Error: fileFullPath is required");
   if (string.IsNullOrEmpty(apiKey))
       throw new Exception("Error: apiKey is required");

   var fi = new FileInfo(fileFullPath);
   var fileContents = File.ReadAllBytes(fi.FullName);
   var fileName = fi.Name;

   Uri uri = new Uri(@"https://bulkapi.zerobounce.net/v2/scoring/sendfile");

   using (var client = new HttpClient())
   using (var request = new HttpRequestMessage(HttpMethod.Post, uri))
   {
       MultipartFormDataContent multiPartContent = new MultipartFormDataContent();
       ByteArrayContent byteArrayContent = new ByteArrayContent(fileContents);
       byteArrayContent.Headers.Add("Content-Type", "text/csv");
       multiPartContent.Add(byteArrayContent, "file", fileName);
       multiPartContent.Add(new StringContent(apiKey), "api_key");
       multiPartContent.Add(new StringContent(emailAddressColumn.ToString()), "email_address_column");
       if (ipAddressColumn != null)
           multiPartContent.Add(new StringContent(ipAddressColumn.ToString()), "ip_address_column");
       if (hasHeaderRow != null)
           multiPartContent.Add(new StringContent((hasHeaderRow == true) ? "true" : "false"), "has_header_row");
       if (returnUrl != null)
           multiPartContent.Add(new StringContent(returnUrl.ToString()), "return_url");

       request.Content = multiPartContent;

       using (var response = await client.SendAsync(request, HttpCompletionOption.ResponseContentRead, CancellationToken.None).ConfigureAwait(false))
       {
           var content = await response.Content.ReadAsStringAsync();

           if (response.IsSuccessStatusCode == false)
           {
               var error = $"StatusCode = {(int)response.StatusCode}, Content = {content}";
               throw new Exception(error);
           }

           return JsonConvert.DeserializeObject<SendFileStatus>(content);
       }
   }
}
   

 <?php

$curl = curl_init();

curl_setopt_array($curl, array(
 CURLOPT_URL => "https://bulkapi.zerobounce.net/v2/scoring/sendfile",
 CURLOPT_RETURNTRANSFER => true,
 CURLOPT_ENCODING => "",
 CURLOPT_MAXREDIRS => 10,
 CURLOPT_TIMEOUT => 30,
 CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
 CURLOPT_CUSTOMREQUEST => "POST",
 CURLOPT_POSTFIELDS => "------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api_key"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="email_address_column"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW--",
 CURLOPT_HTTPHEADER => array(
   "Postman-Token: fae6714d-dc09-4e08-b50d-c97030603b61",
   "cache-control: no-cache",
   "content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
 ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
 echo "cURL Error #:" . $err;
} else {
 echo $response;
}
?>
   

 OkHttpClient client = new OkHttpClient();

 MediaType mediaType = MediaType.parse("multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW");
 RequestBody body = RequestBody.create(mediaType, "------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api_key"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="email_address_column"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW--");
 Request request = new Request.Builder()
   .url("https://bulkapi.zerobounce.net/v2/scoring/sendfile")
   .post(body)
   .addHeader("content-type", "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW")
   .addHeader("cache-control", "no-cache")
   .addHeader("Postman-Token", "25d608ba-6cb5-4c8c-88d7-d47276c67d8e")
   .build();
 
 Response response = client.newCall(request).execute();
   

 import http.client

 conn = http.client.HTTPConnection("bulkapi,zerobounce,net")
 
 payload = "------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api_key"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="email_address_column"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW--"
 
 headers = {
     'content-type': "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW",
     'cache-control': "no-cache",
     'Postman-Token': "bc455eda-9884-417e-b16f-3a5fef3f7540"
     }
 
 conn.request("POST", "v2,sendfile", payload, headers)
 
 res = conn.getresponse()
 data = res.read()
 
 print(data.decode("utf-8"))
   
   

 import Foundation

 let headers = [
   "content-type": "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW",
   "cache-control": "no-cache",
   "Postman-Token": "2f68fcc3-d9b6-458b-b613-56f6a03e6617"
 ]
 let parameters = [
   [
     "name": "api_key",
     "value": "replacewithyours"
   ],
   [
     "name": "email_address_column",
     "value": "replacewithyours"
   ]
 ]
 
 let boundary = "----WebKitFormBoundary7MA4YWxkTrZu0gW"
 
 var body = ""
 var error: NSError? = nil
 for param in parameters {
   let paramName = param["name"]!
   body += "--(boundary)
"
   body += "Content-Disposition:form-data; name="(paramName)""
   if let filename = param["fileName"] {
     let contentType = param["content-type"]!
     let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
     if (error != nil) {
       print(error)
     }
     body += "; filename="(filename)"
"
     body += "Content-Type: (contentType)

"
     body += fileContent
   } else if let paramValue = param["value"] {
     body += "

(paramValue)"
   }
 }
 
 let request = NSMutableURLRequest(url: NSURL(string: "https://bulkapi.zerobounce.net/v2/scoring/sendfile")! as URL, 
                                       cachePolicy: .useProtocolCachePolicy,
                                       timeoutInterval: 10.0)
 request.httpMethod = "POST"
 request.allHTTPHeaderFields = headers
 request.httpBody = postData as Data
 
 let session = URLSession.shared
 let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
   if (error != nil) {
     print(error)
   } else {
     let httpResponse = response as? HTTPURLResponse
     print(httpResponse)
   }
 })
 
 dataTask.resume()
   

// Please select VB or C# language for Send File Sample#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"content-type": @"multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW",
                           @"cache-control": @"no-cache",
                           @"Postman-Token": @"92c5b06e-624f-44e5-bd86-f537bc6cef67" };
NSArray *parameters = @[ @{ @"name": @"api_key", @"value": @"replacewithyours" },
                         @{ @"name": @"email_address_column", @"value": @"replacewithyours" } ];
NSString *boundary = @"----WebKitFormBoundary7MA4YWxkTrZu0gW";

NSError *error;
NSMutableString *body = [NSMutableString string];
for (NSDictionary *param in parameters) {
   [body appendFormat:@"--%@
", boundary];
   if (param[@"fileName"]) {
       [body appendFormat:@"Content-Disposition:form-data; name="%@"; filename="%@"
", param[@"name"], param[@"fileName"]];
       [body appendFormat:@"Content-Type: %@

", param[@"contentType"]];
       [body appendFormat:@"%@", [NSString stringWithContentsOfFile:param[@"fileName"] encoding:NSUTF8StringEncoding error:&error]];
       if (error) {
           NSLog(@"%@", error);
       }
   } else {
       [body appendFormat:@"Content-Disposition:form-data; name="%@"

", param[@"name"]];
       [body appendFormat:@"%@", param[@"value"]];
   }
}
[body appendFormat:@"
--%@--
", boundary];
NSData *postData = [body dataUsingEncoding:NSUTF8StringEncoding];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://bulkapi.zerobounce.net/v2/scoring/sendfile"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"POST"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                           completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                               if (error) {
                                                   NSLog(@"%@", error);
                                               } else {
                                                   NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                   NSLog(@"%@", httpResponse);
                                               }
                                           }];
[dataTask resume];
   

//N/A
   

Endpoint Response

Successful Response

      
{
 "success": true,
 "message": "File Accepted",
 "file_name": "Your file name.csv",
 "file_id": "aaaaaaaa-zzzz-xxxx-yyyy-5003727fffff"
}
   

Error Response

      
   {
     "success": false,
     "message": [
         "Error messages"
     ]
 }
   

AI Scoring API: File Status

/ai-scoring-api/file-status/

The scoring filestatus API returns the file processing status for the file been submitted using sendfile API. Please refer to the C# example for details.

GET /V2/SCORING/FILESTATUS

API URL: https://bulkapi.zerobounce.net/v2/scoring/filestatus

URL Parameters

  • Parameter
    Required/Optional
    Description
  • api_key
    Required
    Your API Key, found in your account
  • file_id
    Required
    The returned file ID when calling scoring sendfile API

If you want to call the API from your browser to test it, all you have to do is to replace the API KEY with your key and the FILE ID with the returned file ID from scoring sendfile

Send File Code Samples

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
  • Android Java
      
' File Status Sample in VB.net

Public Class FileStatus
   Public Property success As Boolean
   Public Property file_id As String
   Public Property file_name As String
   Public Property upload_date As String
   Public Property file_status As String
   Public Property complete_percentage As String
   Public Property return_url As String
End Class

Private Shared Sub FileStatusAPITest()
   Dim apiKey As String = "replace with your api key here"
   Dim fileID As String = "replace with the returned file ID when calling sendfile API"

   Try
       Dim fileStatus As FileStatus = FileStatusAsync(apiKey, fileID).Result
       Console.Write(JsonConvert.SerializeObject(fileStatus, Formatting.Indented))
   Catch ex As Exception
       Console.Write(ex.InnerException.Message)
   End Try

   Console.ReadKey()
End Sub

Public Shared Async Function FileStatusAsync(ByVal apiKey As String, ByVal fileID As String) As Task(Of FileStatus)
   If String.IsNullOrEmpty(apiKey) Then Throw New Exception("Error: apiKey is required")
   If String.IsNullOrEmpty(fileID) Then Throw New Exception("Error: fileID is required")
   Dim uri As Uri = New Uri($"https://bulkapi.zerobounce.net/v2/scoring/filestatus?api_key={apiKey}&file_id={fileID}")

   Using client = New HttpClient()
       Using request = New HttpRequestMessage(HttpMethod.Get, uri)
           Using response = Await client.SendAsync(request).ConfigureAwait(False)
               Dim content = Await response.Content.ReadAsStringAsync()

               If response.IsSuccessStatusCode = False Then
                   Dim error As String = $"StatusCode = {CInt(response.StatusCode)}, Content = {content}"
                   Throw New Exception(error)
               End If

               Return JsonConvert.DeserializeObject(Of FileStatus)(content)
           End Using
       End Using
   End Using
End Function
   

// File Status Sample in C#

public class FileStatus
{
   public bool success { get; set; }
   public string file_id { get; set; }
   public string file_name { get; set; }
   public string upload_date { get; set; }
   public string file_status { get; set; }
   public string complete_percentage { get; set; }
   public string return_url { get; set; }
}

private static void FileStatusAPITest()
{
   string apiKey = "replace with your api key here";
   string fileID = "replace with the returned file ID when calling sendfile API";

   try
   {
       FileStatus fileStatus = FileStatusAsync(apiKey, fileID).Result;
       Console.Write(JsonConvert.SerializeObject(fileStatus, Formatting.Indented));
   }
   catch (Exception ex)
   {
       Console.Write(ex.InnerException.Message);
   }
   Console.ReadKey();
}

public static async Task<FileStatus> FileStatusAsync(string apiKey, string fileID)
{
   if (string.IsNullOrEmpty(apiKey))
       throw new Exception("Error: apiKey is required");
   if (string.IsNullOrEmpty(fileID))
       throw new Exception("Error: fileID is required");

   Uri uri = new Uri($"https://bulkapi.zerobounce.net/v2/scoring/filestatus?api_key={apiKey}&file_id={fileID}");

   using (var client = new HttpClient())
   using (var request = new HttpRequestMessage(HttpMethod.Get, uri))
   using (var response = await client.SendAsync(request).ConfigureAwait(false))
   {
       var content = await response.Content.ReadAsStringAsync();

       if (response.IsSuccessStatusCode == false)
       {
           var error = $"StatusCode = {(int)response.StatusCode}, Content = {content}";
           throw new Exception(error);
       }

       return JsonConvert.DeserializeObject<FileStatus>(content);
   }
}
   

   <?php

   $curl = curl_init();
   
   curl_setopt_array($curl, array(
     CURLOPT_URL => "https://bulkapi.zerobounce.net/v2/scoring/filestatus?api_key=replacewithyours&file_id=replacewithyours",
     CURLOPT_RETURNTRANSFER => true,
     CURLOPT_ENCODING => "",
     CURLOPT_MAXREDIRS => 10,
     CURLOPT_TIMEOUT => 30,
     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
     CURLOPT_CUSTOMREQUEST => "GET",
     CURLOPT_POSTFIELDS => "",
     CURLOPT_HTTPHEADER => array(
       "Postman-Token: 91504cea-f92f-46b0-97a4-338167072887",
       "cache-control: no-cache"
     ),
   ));
   
   $response = curl_exec($curl);
   $err = curl_error($curl);
   
   curl_close($curl);
   
   if ($err) {
     echo "cURL Error #:" . $err;
   } else {
     echo $response;
   }
   ?>
   

   OkHttpClient client = new OkHttpClient();

   Request request = new Request.Builder()
     .url("https://bulkapi.zerobounce.net/v2/scoring/filestatus?api_key=replacewithyours&file_id=replacewithyours")
     .get()
     .addHeader("cache-control", "no-cache")
     .addHeader("Postman-Token", "7fffd7a4-b2fd-4e8b-ac85-4099411f27ce")
     .build();
   
   Response response = client.newCall(request).execute();
   

   import http.client

   conn = http.client.HTTPConnection("bulkapi,zerobounce,net")
   
   payload = ""
   
   headers = {
       'cache-control': "no-cache",
       'Postman-Token': "caa917fe-45ce-45ae-9456-2b039b999dcb"
       }
   
   conn.request("GET", "v2,filestatus", payload, headers)
   
   res = conn.getresponse()
   data = res.read()
   
   print(data.decode("utf-8"))
   
   

   // Please select VB or C# language for File Status Sampleimport Foundation

   let headers = [
     "cache-control": "no-cache",
     "Postman-Token": "4f1b92e2-034f-4fa0-94d9-b097d768668a"
   ]
   
   let request = NSMutableURLRequest(url: NSURL(string: "https://bulkapi.zerobounce.net/v2/scoring/filestatus?api_key=replacewithyours&file_id=replacewithyours")! as URL,
                                           cachePolicy: .useProtocolCachePolicy,
                                       timeoutInterval: 10.0)
   request.httpMethod = "GET"
   request.allHTTPHeaderFields = headers
   
   let session = URLSession.shared
   let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
     if (error != nil) {
       print(error)
     } else {
       let httpResponse = response as? HTTPURLResponse
       print(httpResponse)
     }
   })
   
   dataTask.resume()
   

   #import <Foundation/Foundation.h>

   NSDictionary *headers = @{ @"cache-control": @"no-cache",
                              @"Postman-Token": @"5e9c24ae-b577-4e33-8748-83f14e151ae9" };
   
   NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://bulkapi.zerobounce.net/v2/scoring/filestatus?api_key=replacewithyours&file_id=replacewithyours"]
                                                          cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                      timeoutInterval:10.0];
   [request setHTTPMethod:@"GET"];
   [request setAllHTTPHeaderFields:headers];
   
   NSURLSession *session = [NSURLSession sharedSession];
   NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                               completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                   if (error) {
                                                       NSLog(@"%@", error);
                                                   } else {
                                                       NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                       NSLog(@"%@", httpResponse);
                                                   }
                                               }];
   [dataTask resume];
   

// N/A
   

Endpoint Response

Successful Response

      
{
 "success": true,
 "file_id": "aaaaaaaa-zzzz-xxxx-yyyy-5003727fffff",
 "file_name": "Your file name.csv",
 "upload_date": "10/20/2018 4:35:58 PM",
 "file_status": "Complete",
 "complete_percentage": "100%",
 "return_url": "Your return URL if provided when calling sendfile API"
}
   

Error Response


   {      
     "success": false,
     "message": "Error messages"
   }
   

AI Scoring API: Get File

/ai-scoring-api/get-file/

The scoring getfile API allows users to get the validation results file for the file been submitted using scoring sendfile API. Please refer to the C# example for details.

GET /V2/SCORING/GETFILE

API URL: https://bulkapi.zerobounce.net/v2/scoring/getfile

URL Parameters

  • Parameter
    Required/Optional
    Description
  • api_key
    Required
    Your API Key, found in your account
  • file_id
    Required
    The returned file ID when calling scoring sendfile API

Send File Code Samples

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
  • Android Java
      
' Send File Sample in VB.net

Public Class SendFileStatus
   Public Property success As Boolean
   Public Property message As String
   Public Property file_name As String
   Public Property file_id As String
End Class

Private Shared Sub SendFileAPITest()
   Dim fileFullPath As String = $"full file path of a csv or txt file"  ' required
   Dim apiKey As String = "replace with your api key here"              ' required
   Dim emailAddressColumn As Integer = 2  ' required
   Dim ipAddressColumn As Integer? = 11   ' optional
   Dim hasHeaderRow As Boolean? = True    ' optional
   Dim returnUrl As String = Nothing      ' optional

   Try
       Dim sendFileStatus As SendFileStatus = SendFile(fileFullPath, apiKey, emailAddressColumn, ipAddressColumn, hasHeaderRow, returnUrl).Result
       Console.Write(JsonConvert.SerializeObject(sendFileStatus, Formatting.Indented))
   Catch ex As Exception
       Console.Write(ex.InnerException.Message)
   End Try

   Console.ReadKey()
End Sub

Public Shared Async Function SendFile(ByVal fileFullPath As String, 
                                     ByVal apiKey As String, 
                                     ByVal emailAddressColumn As Integer, 
                                     ByVal Optional ipAddressColumn As Integer? = Nothing, 
                                     ByVal Optional hasHeaderRow As Boolean? = Nothing, 
                                     ByVal Optional returnUrl As String = Nothing) As Task(Of SendFileStatus)

   If String.IsNullOrEmpty(fileFullPath) Then Throw New Exception("Error: fileFullPath is required")
   If String.IsNullOrEmpty(apiKey) Then Throw New Exception("Error: apiKey is required")
   Dim fi = New FileInfo(fileFullPath)
   Dim fileContents = File.ReadAllBytes(fi.FullName)
   Dim fileName = fi.Name
   Dim uri As Uri = New Uri("https://bulkapi.zerobounce.net/v2/scoring/sendfile")

   Using client = New HttpClient()

       Using request = New HttpRequestMessage(HttpMethod.Post, uri)
           Dim multiPartContent As MultipartFormDataContent = New MultipartFormDataContent()
           Dim byteArrayContent As ByteArrayContent = New ByteArrayContent(fileContents)
           byteArrayContent.Headers.Add("Content-Type", "text/csv")
           multiPartContent.Add(byteArrayContent, "file", fileName)
           multiPartContent.Add(New StringContent(apiKey), "api_key")
           multiPartContent.Add(New StringContent(emailAddressColumn.ToString()), "email_address_column")
           If ipAddressColumn IsNot Nothing Then multiPartContent.Add(New StringContent(ipAddressColumn.ToString()), "ip_address_column")
           If hasHeaderRow IsNot Nothing Then multiPartContent.Add(New StringContent(If((hasHeaderRow = True), "true", "false")), "has_header_row")
           If returnUrl IsNot Nothing Then multiPartContent.Add(New StringContent(returnUrl.ToString()), "return_url")
           request.Content = multiPartContent

           Using response = Await client.SendAsync(request, HttpCompletionOption.ResponseContentRead, CancellationToken.None).ConfigureAwait(False)
               Dim content = Await response.Content.ReadAsStringAsync()

               If response.IsSuccessStatusCode = False Then
                   Dim error As String = $"StatusCode = {CInt(response.StatusCode)}, Content = {content}"
                   Throw New Exception(error)
               End If

               Return JsonConvert.DeserializeObject(Of SendFileStatus)(content)
           End Using
       End Using
   End Using
End Function
   

// Send File Sample in C#

public class SendFileStatus
{
   public bool success { get; set; }
   public string message { get; set; }
   public string file_name { get; set; }
   public string file_id { get; set; }
}

private static void SendFileAPITest()
{
   string fileFullPath = $"full file path of a csv or txt file";  //required
   string apiKey = "replace with your api key here";  //required       
   int emailAddressColumn = 2;  //required
   int? ipAddressColumn = 11;  //optional
   bool? hasHeaderRow = true;  //optional
   string returnUrl = null;  //optional

   try
   {
       SendFileStatus sendFileStatus = SendFile(fileFullPath, apiKey, emailAddressColumn, ipAddressColumn, hasHeaderRow, returnUrl).Result;
       Console.Write(JsonConvert.SerializeObject(sendFileStatus, Formatting.Indented));
   }
   catch (Exception ex)
   {
       Console.Write(ex.InnerException.Message);
   }

   Console.ReadKey();
}

public static async Task<SendFileStatus> SendFile(string fileFullPath, string apiKey, int emailAddressColumn, 
                                           int? ipAddressColumn = null, bool? hasHeaderRow = null, string returnUrl = null)
{
   if (string.IsNullOrEmpty(fileFullPath))
       throw new Exception("Error: fileFullPath is required");
   if (string.IsNullOrEmpty(apiKey))
       throw new Exception("Error: apiKey is required");

   var fi = new FileInfo(fileFullPath);
   var fileContents = File.ReadAllBytes(fi.FullName);
   var fileName = fi.Name;

   Uri uri = new Uri(@"https://bulkapi.zerobounce.net/v2/scoring/sendfile");

   using (var client = new HttpClient())
   using (var request = new HttpRequestMessage(HttpMethod.Post, uri))
   {
       MultipartFormDataContent multiPartContent = new MultipartFormDataContent();
       ByteArrayContent byteArrayContent = new ByteArrayContent(fileContents);
       byteArrayContent.Headers.Add("Content-Type", "text/csv");
       multiPartContent.Add(byteArrayContent, "file", fileName);
       multiPartContent.Add(new StringContent(apiKey), "api_key");
       multiPartContent.Add(new StringContent(emailAddressColumn.ToString()), "email_address_column");
       if (ipAddressColumn != null)
           multiPartContent.Add(new StringContent(ipAddressColumn.ToString()), "ip_address_column");
       if (hasHeaderRow != null)
           multiPartContent.Add(new StringContent((hasHeaderRow == true) ? "true" : "false"), "has_header_row");
       if (returnUrl != null)
           multiPartContent.Add(new StringContent(returnUrl.ToString()), "return_url");

       request.Content = multiPartContent;

       using (var response = await client.SendAsync(request, HttpCompletionOption.ResponseContentRead, CancellationToken.None).ConfigureAwait(false))
       {
           var content = await response.Content.ReadAsStringAsync();

           if (response.IsSuccessStatusCode == false)
           {
               var error = $"StatusCode = {(int)response.StatusCode}, Content = {content}";
               throw new Exception(error);
           }

           return JsonConvert.DeserializeObject<SendFileStatus>(content);
       }
   }
}
   

 <?php

$curl = curl_init();

curl_setopt_array($curl, array(
 CURLOPT_URL => "https://bulkapi.zerobounce.net/v2/scoring/sendfile",
 CURLOPT_RETURNTRANSFER => true,
 CURLOPT_ENCODING => "",
 CURLOPT_MAXREDIRS => 10,
 CURLOPT_TIMEOUT => 30,
 CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
 CURLOPT_CUSTOMREQUEST => "POST",
 CURLOPT_POSTFIELDS => "------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api_key"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="email_address_column"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW--",
 CURLOPT_HTTPHEADER => array(
   "Postman-Token: fae6714d-dc09-4e08-b50d-c97030603b61",
   "cache-control: no-cache",
   "content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
 ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
 echo "cURL Error #:" . $err;
} else {
 echo $response;
}
?>
   

 OkHttpClient client = new OkHttpClient();

 MediaType mediaType = MediaType.parse("multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW");
 RequestBody body = RequestBody.create(mediaType, "------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api_key"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="email_address_column"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW--");
 Request request = new Request.Builder()
   .url("https://bulkapi.zerobounce.net/v2/scoring/sendfile")
   .post(body)
   .addHeader("content-type", "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW")
   .addHeader("cache-control", "no-cache")
   .addHeader("Postman-Token", "25d608ba-6cb5-4c8c-88d7-d47276c67d8e")
   .build();
 
 Response response = client.newCall(request).execute();
   

 import http.client

 conn = http.client.HTTPConnection("bulkapi,zerobounce,net")
 
 payload = "------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api_key"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="email_address_column"

replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW--"
 
 headers = {
     'content-type': "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW",
     'cache-control': "no-cache",
     'Postman-Token': "bc455eda-9884-417e-b16f-3a5fef3f7540"
     }
 
 conn.request("POST", "v2,sendfile", payload, headers)
 
 res = conn.getresponse()
 data = res.read()
 
 print(data.decode("utf-8"))
   
   

 import Foundation

 let headers = [
   "content-type": "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW",
   "cache-control": "no-cache",
   "Postman-Token": "2f68fcc3-d9b6-458b-b613-56f6a03e6617"
 ]
 let parameters = [
   [
     "name": "api_key",
     "value": "replacewithyours"
   ],
   [
     "name": "email_address_column",
     "value": "replacewithyours"
   ]
 ]
 
 let boundary = "----WebKitFormBoundary7MA4YWxkTrZu0gW"
 
 var body = ""
 var error: NSError? = nil
 for param in parameters {
   let paramName = param["name"]!
   body += "--(boundary)
"
   body += "Content-Disposition:form-data; name="(paramName)""
   if let filename = param["fileName"] {
     let contentType = param["content-type"]!
     let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
     if (error != nil) {
       print(error)
     }
     body += "; filename="(filename)"
"
     body += "Content-Type: (contentType)

"
     body += fileContent
   } else if let paramValue = param["value"] {
     body += "

(paramValue)"
   }
 }
 
 let request = NSMutableURLRequest(url: NSURL(string: "https://bulkapi.zerobounce.net/v2/scoring/sendfile")! as URL, 
                                       cachePolicy: .useProtocolCachePolicy,
                                       timeoutInterval: 10.0)
 request.httpMethod = "POST"
 request.allHTTPHeaderFields = headers
 request.httpBody = postData as Data
 
 let session = URLSession.shared
 let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
   if (error != nil) {
     print(error)
   } else {
     let httpResponse = response as? HTTPURLResponse
     print(httpResponse)
   }
 })
 
 dataTask.resume()
   

// Please select VB or C# language for Send File Sample#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"content-type": @"multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW",
                           @"cache-control": @"no-cache",
                           @"Postman-Token": @"92c5b06e-624f-44e5-bd86-f537bc6cef67" };
NSArray *parameters = @[ @{ @"name": @"api_key", @"value": @"replacewithyours" },
                         @{ @"name": @"email_address_column", @"value": @"replacewithyours" } ];
NSString *boundary = @"----WebKitFormBoundary7MA4YWxkTrZu0gW";

NSError *error;
NSMutableString *body = [NSMutableString string];
for (NSDictionary *param in parameters) {
   [body appendFormat:@"--%@
", boundary];
   if (param[@"fileName"]) {
       [body appendFormat:@"Content-Disposition:form-data; name="%@"; filename="%@"
", param[@"name"], param[@"fileName"]];
       [body appendFormat:@"Content-Type: %@

", param[@"contentType"]];
       [body appendFormat:@"%@", [NSString stringWithContentsOfFile:param[@"fileName"] encoding:NSUTF8StringEncoding error:&error]];
       if (error) {
           NSLog(@"%@", error);
       }
   } else {
       [body appendFormat:@"Content-Disposition:form-data; name="%@"

", param[@"name"]];
       [body appendFormat:@"%@", param[@"value"]];
   }
}
[body appendFormat:@"
--%@--
", boundary];
NSData *postData = [body dataUsingEncoding:NSUTF8StringEncoding];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://bulkapi.zerobounce.net/v2/scoring/sendfile"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"POST"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                           completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                               if (error) {
                                                   NSLog(@"%@", error);
                                               } else {
                                                   NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                   NSLog(@"%@", httpResponse);
                                               }
                                           }];
[dataTask resume];
   

//N/A
   

Endpoint Response

Successful Response

      
{
 "success": true,
 "message": "File Accepted",
 "file_name": "Your file name.csv",
 "file_id": "aaaaaaaa-zzzz-xxxx-yyyy-5003727fffff"
}
   

Error Response

      
   {
     "success": false,
     "message": [
         "Error messages"
     ]
 }
   

AI Scoring API: Delete File

/ai-scoring-api/delete-file/

The scoring deletefile API deletes the file that was submitted using scoring sendfile API. File can be deleted only when its status is Complete.

POST /V2/SCORING/DELETEFILE

API URL: https://bulkapi.zerobounce.net/v2/scoring/deletefile

URL Parameters

  • Parameter
    Required/Optional
    Description
  • api_key
    Required
    Your API Key, found in your account
  • file_id
    Required
    The returned file ID when calling scoring sendfile API

Delete File Code Samples

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
      
' Delete File Sample in VB.net

Public Class ResponseResult
   Public Property success As Boolean
   Public Property message As String
   Public Property file_id As String
   Public Property file_name As String
End Class

Private Shared Sub DeleteFileAPITest()
   Dim apiKey As String = "replace with your api key here"
   Dim fileID As String = "replace with the returned file ID when calling sendfile API"

   Try
       Dim responseResult As ResponseResult = DeleteFileAsync(apiKey, fileID).Result
       Console.Write(JsonConvert.SerializeObject(responseResult, Formatting.Indented))
   Catch ex As Exception
       Console.Write(ex.InnerException.Message)
   End Try

   Console.ReadKey()
End Sub

Public Shared Async Function DeleteFileAsync(ByVal apiKey As String, ByVal fileID As String) As Task(Of ResponseResult)
   If String.IsNullOrEmpty(apiKey) Then Throw New Exception("Error: apiKey is required")
   If String.IsNullOrEmpty(fileID) Then Throw New Exception("Error: fileID is required")
   Dim uri As Uri = New Uri($"https://bulkapi.zerobounce.net/v2/scoring/deletefile?api_key={apiKey}&file_id={fileID}")

   Using client = New HttpClient()

       Using request = New HttpRequestMessage(HttpMethod.[Get], uri)

           Using response = Await client.SendAsync(request).ConfigureAwait(False)
               Dim content = Await response.Content.ReadAsStringAsync()

               If response.IsSuccessStatusCode = False Then
                   Dim [error] = $"StatusCode = {CInt(response.StatusCode)}, Content = {content}"
                   Throw New Exception([error])
               End If

               Return JsonConvert.DeserializeObject(Of ResponseResult)(content)
           End Using
       End Using
   End Using
End Function
   

// Delete File Sample in C#

public class ResponseResult
{
   public bool success { get; set; }
   public string message { get; set; }
   public string file_id { get; set; }
   public string file_name { get; set; }
}

private static void DeleteFileAPITest()
{
   string apiKey = "replace with your api key here";
   string fileID = "replace with the returned file ID when calling sendfile API";

   try
   {
       ResponseResult responseResult = DeleteFileAsync(apiKey, fileID).Result;
       Console.Write(JsonConvert.SerializeObject(responseResult, Formatting.Indented));
   }
   catch (Exception ex)
   {
       Console.Write(ex.InnerException.Message);
   }
   Console.ReadKey();
}

public static async Task<ResponseResult> DeleteFileAsync(string apiKey, string fileID)
{
   if (string.IsNullOrEmpty(apiKey))
       throw new Exception("Error: apiKey is required");
   if (string.IsNullOrEmpty(fileID))
       throw new Exception("Error: fileID is required");

   Uri uri = new Uri($"https://bulkapi.zerobounce.net/v2/scoring/deletefile?api_key={apiKey}&file_id={fileID}");

   using (var client = new HttpClient())
   using (var request = new HttpRequestMessage(HttpMethod.Get, uri))
   using (var response = await client.SendAsync(request).ConfigureAwait(false))
   {
       var content = await response.Content.ReadAsStringAsync();

       if (response.IsSuccessStatusCode == false)
       {
           var error = $"StatusCode = {(int)response.StatusCode}, Content = {content}";
           throw new Exception(error);
       }

       return JsonConvert.DeserializeObject<ResponseResult>(content);
   }
}
   

 <?php

 $curl = curl_init();
 
 curl_setopt_array($curl, array(
   CURLOPT_URL => "https://bulkapi.zerobounce.net/v2/scoring/deletefile?api_key=replacewithyours&file_id=replacewithyours",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 30,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "GET",
   CURLOPT_POSTFIELDS => "",
   CURLOPT_HTTPHEADER => array(
     "Postman-Token: 91504cea-f92f-46b0-97a4-338167072887",
     "cache-control: no-cache"
   ),
 ));
 
 $response = curl_exec($curl);
 $err = curl_error($curl);
 
 curl_close($curl);
 
 if ($err) {
   echo "cURL Error #:" . $err;
 } else {
   echo $response;
 }
 ?>
   

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
 .url("https://bulkapi.zerobounce.net/v2/scoring/deletefile?api_key=replacewithyours&file_id=replacewithyours")
 .get()
 .addHeader("cache-control", "no-cache")
 .addHeader("Postman-Token", "7fffd7a4-b2fd-4e8b-ac85-4099411f27ce")
 .build();

Response response = client.newCall(request).execute();
   

import http.client

conn = http.client.HTTPConnection("bulkapi,zerobounce,net")

payload = ""

headers = {
   'cache-control': "no-cache",
   'Postman-Token': "caa917fe-45ce-45ae-9456-2b039b999dcb"
   }

conn.request("GET", "v2,deletefile", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
   
   

// Please select VB or C# language for File Status Sampleimport Foundation

let headers = [
 "cache-control": "no-cache",
 "Postman-Token": "4f1b92e2-034f-4fa0-94d9-b097d768668a"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://bulkapi.zerobounce.net/v2/scoring/deletefile?api_key=replacewithyours&file_id=replacewithyours")! as URL,
                                       cachePolicy: .useProtocolCachePolicy,
                                   timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
 if (error != nil) {
   print(error)
 } else {
   let httpResponse = response as? HTTPURLResponse
   print(httpResponse)
 }
})

dataTask.resume()
   

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"cache-control": @"no-cache",
                           @"Postman-Token": @"5e9c24ae-b577-4e33-8748-83f14e151ae9" };

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://bulkapi.zerobounce.net/v2/scoring/deletefile?api_key=replacewithyours&file_id=replacewithyours"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"GET"];
[request setAllHTTPHeaderFields:headers];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
       completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
           if (error) {
               NSLog(@"%@", error);
           } else {
               NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
               NSLog(@"%@", httpResponse);
           }
       }];
[dataTask resume];
   

Endpoint Response

Successful Response

      
 {
   "success": true,
   "message": "File Deleted",
   "file_name": "test2",
   "file_id": "b222a0fd-90d5-416c-8f1a-9cc3851fc823"
 }
   

Error Response

      
{
 "success": false,
 "message": "File cannot be found."
}