📘

This endpoint returns an application/octet-stream containing the job data as a CSV file. Because of this, the API explorer is not available.

There are several options that allow you download additional information about each string as well as several segmentation options available. The only required parameters for this endpoint are the API key and id of the job to download results from. Below is an example of a basic request that will return all five result codes.

curl -X GET\
  --url 'https://api.neverbounce.com/v4/jobs/download?key={api_key}&job_id={job_id}'

# The same request with explicitly defined parameters
curl -X GET\
  --url 'https://api.neverbounce.com/v4/jobs/download?key={api_key}&job_id={job_id}&valids=1&invalids=1&catchalls=1&unknowns=1&disposables=1&include_duplicates=0&email_status=1'
# The same request as POST with explicitly defined parameters
curl -X POST\
  --url 'https://api.neverbounce.com/v4/jobs/download'\
  --data key={api_key}\
  --data job_id={job_id}

# The same request as POST with explicitly defined parameters
curl -X POST\
  --url 'https://api.neverbounce.com/v4/jobs/download'\
  --data key={api_key}\
  --data job_id={job_id}\
  --data valids=1\
  --data invalids=1\
  --data catchalls=1\
  --data unknowns=1\
  --data disposables=1\
  --data include_duplicates=0\
  --data email_status=1
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

$query = [
];

// Download the job data as a CSV
$job = \NeverBounce\Jobs::download($job_id, $query);
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Create download query
const query = {};

// Download the results as a CSV
client.jobs.download(jobId, query).then(
    resp => // Handle successful response,
    err => // Handle error response
);
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Open file to write to
f = open('results.csv', mode='wb')

# Jobs download
resp = client.jobs_download(job_id=289022, fd=f)
f.close()
// Instantiate wrapper
client := neverbounce.New("api_key")

// Download the jobs results as a CSV and save to file
err := client.Jobs.Download(&nbModels.JobsDownloadRequestModel{
  JobID:            296050,
  // ...See JobsDownloadRequestModel for additional options
}, "test.csv")
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Download job as CSV
resp = client.jobs_download(job_id: 123)

# Parse CSV data
emails = CSV.parse(resp.raw)
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Create job download model
var model = new JobDownloadRequestModel();
model.job_id = 290561;
// See model for additional options

// Download jobs' data
String resp = await sdk.Jobs.Download(model);
id,email,name,email_status
"12345","[email protected]","Fred McValid",valid
"12346","[email protected]","Bob McInvalid",invalid

Parameters

Segmentation

ParameterDescription
validsIncludes or excludes valid emails
invalidsIncludes or excludes invalid emails
catchallsIncludes or excludes catchall (accept all / unverifiable) emails
unknownsIncludes or excludes unknown emails
disposablesIncludes or excludes disposable emails
include_duplicatesIf true then all instances of duplicated items will appear.
only_duplicatesIf set this property overrides other segmentation options and the download will only return the duplicated items.
only_bad_syntaxIf set this property overrides other segmentation options and the download will only return bad syntax records.

Appends

ParameterDescription
bad_syntaxAppends a yes/no column indicating if the record is bad syntax
free_email_hostAppends a yes/no column indicating if the email is a freemail address (e.g. gmail.com, hotmail.com, yahoo.com)
role_accountAppends a yes/no column indicating if the email is a role account (e.g. support@, info@, sales@)
addrAppends a column indicating the address portion of the email. Generally, ​this is anything before the @ sign. If this address includes an email alias, the alias will not be returned as part of this field.
aliasAppends a column showing the alias portion of an email address. If an address contains an alias such as "[email protected]" the alias portion is returned, otherwi​se this column is empty.
hostAppends a column showing the host portion of the email address. Generally this is everything after the @ sign.
subdomainAppends a column to show the email host's subdomain if applicable. For example, if the host was site.example.com, the subdomain would show a response of "site".
domainAppends a column to show the email host's domain name. This does not include any subdomain, if applicable, and does not include the TLD or top level domain portion. If the host was site.example.com, the domain would be "example".
tldAppends a column to show the TLD or top level domain of the email host. If the host was "site.example.com", the TLD is "com".
fqdnAppends a column to show the FQDN or "Fully Qualified Domain Name". This is the portion of the host that you use to query DNS information. In most cases, this will be the same as the host; however, if a subdomain was included this will be removed from the FQDN. For example, if the host was "zone-1.zone-2.site.example.com", the FQDN would be "example.com".
networkAppends a column to show the FQDN (Fully Qualified Domain Name) of the primary MX record. This is an attempt to determine the ISP hosting the email at a particular address and is useful for grouping addresses together by provider.
has_dns_infoAppends a column to show whether one or more DNS records exists for this host.
has_mail_serverAppends a column to show whether this host has one or more MX records defined in its DNS records.
mail_server_reachableAppends a column to show whether NeverBounce was able to connect to a remote mail server identified by the host's MX records.
email_status_intAppends the verification result code as an integer (0, 1, 2, 3, 4).
email_statusAppends the verification result code as a string (valid, invalid, disposable, catchall, unknown).

Settings

ParameterDescription
binary_operators_typeDetermines how Yes/No columns are represented. Available settings are:

BIN_1_0 = 1/0 (default)
BIN_Y_N = Y/N
BIN_y_n = y/n
BIN_yes_no = yes/no
BIN_Yes_No = Yes/No
BIN_true_false = true/false
line_feed_typeDetermines the type of linefeed character used to represent line breaks in the CSV. Available settings are:

LINEFEED_0A0D = \n\r (default)
LINEFEED_0D0A = \r\n
LINEFEED_0A = \n
LINEFEED_0D = \r