/create

📘

Usage Guidelines

Please be sure to review our usage guidelines for the bulk API here.

The jobs create endpoint allows you create verify multiple emails together, the same way you would verify lists in the dashboard. This endpoint will create a job and process the emails in the list (if auto_start is enabled) asynchronously. Verification results are not returned in the response. Read more about how to verify lists of emails here.

Auto Parse

This will enable or disable the indexing process from automatically starting as soon as you create a job. If set to 0 or false you will need to call the /parse endpoint after the job has been created to begin indexing. Defaults to 0

Auto Start

This will enable or disable the job from automatically beginning the verification process once it has been parsed. If this is set to 0 or false you will need to call the /start endpoint to begin verification. Setting this to 1 or true will start the job and deduct the credits. Defaults to 0

Run Sample

This endpoint has the ability to run a sample on the list and provide you with an estimated bounce rate without costing you. Based on the estimated bounce rate you can decide whether or not to perform the full validation or not. You can start validation by calling the /start endpoint. Read more about running a sample here. Defaults to 0

Input & Input Location

This endpoint can receive input in multiple ways. The input_location parameter describes the contents of the input parameter. The input parameter may be an array of objects containing emails or a file hosted at a remote URI.

Remote URL

Using a remote URL allows you to host the file and provide us with a direct link to it. The file should be a list of emails separated by line breaks or a standard CSV file. We support most common file transfer protocols and their authentication mechanisms. When using a URL that requires authentication be sure to pass the username and password in the URI string.

# Basic url
http://example.com/full/path/to/file.csv

# HTTP Basic Auth
http://name:[email protected]/full/path/to/file.csv

# FTP with authentication
ftp://name:[email protected]:21/full/path/to/file.csv

id,email,name
"12345","[email protected]","Fred McValid"
"12346","[email protected]","Bob McInvalid"

Supplied Data

Supplying the data directly gives you the option to dynamically create email lists on the fly rather than having to write to a file. input will accept an array of objects or arrays that contain the email, as well as any ancillary data you wish to associate with the email (e.g. user IDs, names, contact information).

If the data is supplied as an object, the key names will be used for the column headers. If the data is supplied as an array, column headers will be omitted. Below is a sample of what each looks like in JSON.

🚧

Our API enforces a max request size of 25 Megabytes. If you surpass this limit you'll receive a 413 Entity Too Large error from the server. For payloads that exceed 25 Megabytes we suggest using the remote_url method or removing any ancillary data sent with the emails.

[
    {
        "id": 12345,
        "email": "[email protected]",
        "name": "Fred McValid"
    },
    {
        "id": 12346,
        "email": "[email protected]",
        "name": "Bob McInvalid"
    }
]

[
    [
        12345,
        "[email protected]",
        "Fred McValid"
    ],
    [
        12346,
        "[email protected]",
        "Bob McInvalid"
    ]
]

Manual Reviews

Our manual review process allows us to take a second look at jobs that have a high rate of unknowns. Often we can re-run lists at a later time or under specific configurations to further resolve these unknowns. This requires a member of our team to perform these reviews so they only occur during our normal business hours.

While this works well for most dashboard users, this isn't always optimal for API users who programmatically access their lists. Starting in 4.2 we've introduced the allow_manual_review to allow users to opt-into this featured when creating their API jobs.

If a allow_manual_review is enabled, your job may take up to 1 business day to be released if it falls into the manual review queue. The job status will include the under_review job status if it's in this queue.

Callback URL and Headers

To enable callbacks to your application you must supply an accessible URL in the callback_url parameter. This URL should start with either http:// or https:// and be accessible over the internet. You can supply basic authentication credentials directly in the URL.

# Basic url
https://example.com/webhooks/neverbounce

# HTTPS with Basic Auth
https://name:[email protected]/webhooks/neverbounce

You can also specific headers to include in the callback requests with the callback_headers parameter. You can use these to set an authorization token or internal reference for the job.

curl --request POST\
  --header "Content-Type: application/json"\
  --url https://api.neverbounce.com/v4.2/jobs/create\
  --data '{
    "key": {api_key},
    "input_location": "supplied",
    "filename": "SampleNeverBounceAPI.csv",
    "auto_start": true,
    "auto_parse": true,
    "callback_url": "https://example.com/callbacks/neverbounce",
    "callback_headers": {
        "X-My-Token": "abc123"
    }, 
    "input": [
        [
            "[email protected]",
            "Fred McValid"
        ],
        [
            "[email protected]",
            "Bob McInvalid"
        ]
    ]
}'

For more information about callbacks and a list of supported events see job callbacks.