Back

NeverBounce API Essential Guide

Aug 18, 20246 minute read

What type of API does NeverBounce provide?

NeverBounce uses a REST API.

Key points:

  • The NeverBounce API is described as a "common RESTful API".
  • All requests are performed via HTTPS connections.
  • Responses are returned as JSON.

Details:

  • The API uses widely-accepted formats to allow easy use with common programming languages and development kits.
  • It is designed to be portable, expandable, and secure.
  • The documentation provides descriptions of various endpoints, parameters they accept, and responses they send.

Best practices:

  • The standard API is not suitable for use in client-side scripts (e.g. jQuery, JavaScript) as it would expose sensitive API credentials.
  • For client-side usage, NeverBounce recommends using their JavaScript Widget instead.

Additional information:

NeverBounce provides API wrappers for several programming languages including PHP, Ruby, NodeJS, Python, Go, .NET, and Java. These wrappers likely make it easier to integrate the REST API into applications built with those languages.

Does the NeverBounce API have webhooks?

Webhooks in NeverBounce API

Yes, the official NeverBounce API does have webhooks, but they are limited in scope and functionality.

Types of Events

The NeverBounce API doesn't offer a wide range of events to subscribe to via webhooks. Instead, it provides a specific webhook functionality for email verification. The main use case for webhooks in NeverBounce is for single email verification, which can be integrated into existing tools or CRMs.

Key Points to Consider

  1. The webhook functionality is primarily used with the single/check endpoint.

  2. To create a webhook, you need to follow a specific link provided by NeverBounce, which will give you a URL with a webhook secret key.

  3. The webhook URL looks like this:

    https://api.neverbounce.com/v4.2/single/check?key=webhook_secret_abcdefghijklmnopqrstuvwxyz&email={email}
    

    You replace {email} with the email you want to verify.

  4. Additional parameters like address_info and credits_info can be added to the webhook URL for more detailed information.

  5. It's important to note that these webhooks are not safe to use in client-side scripts (e.g., jQuery, JavaScript) because they contain sensitive API keys.

Best Practices

  1. Use webhooks for single email verification in response to specific actions, like form submissions or button clicks.

  2. Do not use single verification (including webhooks) for verifying emails in an existing list or database one-by-one. This may result in your account being locked.

  3. For bulk verification of email lists or databases, use the bulk verification feature instead of webhooks.

  4. Treat the webhook URL and its secret key with the same level of security as you would treat a regular API key.

In summary, while NeverBounce does offer webhook functionality, it's primarily designed for single email verification integration rather than a comprehensive event subscription system. For more complex use cases or bulk verifications, you should consider using other features of the NeverBounce API.

Rate Limits and other limitations

Here are the key points about the API rate limits for the NeverBounce API:

Bulk Verification Limits

  • Do not create more than 10 jobs for every 100k items per hour [1]
  • Maximum payload size of 25MB when using the supplied_data method [1][2]
  • Exceeding the 25MB limit will result in a 413 error code [1][2]

General Guidelines

  • Buffer data locally and submit as a single job rather than submitting chunks separately [1]
  • Sending too many small jobs in a short time can result in account locking and API access being disabled [1]

Throttling

  • The API has throttling in place to prevent excessive requests [3]
  • If throttle is triggered, you'll receive a "throttle_triggered" error [3]
  • This indicates too many requests in a short time - you should try again shortly or adjust rate limit settings [3]

Other Limits

  • There are no specific limits mentioned for single email verification requests
  • Callback URLs and headers can be used, but no rate limits are specified for these [2]

Best Practices

  • Buffer data locally when possible and submit in bulk rather than many small requests [1]
  • Handle throttling errors by implementing backoff and retry logic [3]
  • Monitor your usage to stay within the bulk job creation limits [1]
  • Consider using the remote_url method for payloads exceeding 25MB [2]

The NeverBounce API implements rate limiting and payload size restrictions primarily on bulk verification jobs. Following their usage guidelines and implementing proper error handling will help ensure smooth API usage within the specified limits.

Latest API Version

Based on the search results provided, the most recent version of the NeverBounce API appears to be V4. Here are the key points:

API Version

  • The current version of the NeverBounce API is V4 [1][2].

Key Points

  • The NeverBounce API is a RESTful API that uses HTTPS connections and returns responses as JSON [2].

  • The API is not suitable for direct use in client-side scripts (e.g. jQuery, Javascript) due to security concerns. A Javascript Widget is provided for client-side use instead [2].

  • API requests are authenticated using an API key that looks like this: secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx [3][5].

API Wrappers

NeverBounce provides official API wrappers for several programming languages, including:

  • PHP
  • Ruby
  • NodeJS
  • Python
  • Go
  • .NET
  • Java [2]

Best Practices

  • Use the provided API wrappers when possible for easier integration [2].

  • When making API requests, always use HTTPS and include your API key for authentication [2][3][5].

  • Be aware that the V3 API credentials (username and secret key) will not work with the V4 API. You need to obtain new V4 API credentials [3][5].

  • When working with bulk jobs, you can attach metadata to each email object in the job input listing [5].

  • For paginated results (like job searches), use the provided iterator methods to handle pagination automatically [5].

Code Example

Here's a basic example of using the Python SDK to check a single email:

import neverbounce_sdk api_key = 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' client = neverbounce_sdk.client(api_key=api_key, timeout=30) resp = client.single_check('[email protected]') print(resp['result']) # e.g., 'invalid' print(resp['execution_time']) # e.g., 285

This example demonstrates how to initialize the client with your API key and perform a single email check [5].

How to get a NeverBounce developer account and API Keys?

To get a developer account for NeverBounce and create an API integration, follow these steps:

  1. Create a NeverBounce account:

    • Go to the NeverBounce website and sign up for an account if you don't already have one.
  2. Log in to your NeverBounce account:

    • Access your dashboard after logging in.
  3. Create a Custom Integration App:

    • In your account dashboard, look for an option to create a new Custom Integration App.
    • This step is crucial as it will generate your API key.
  4. Access your API key:

    • After creating the Custom Integration App, you'll be taken to the app's overview page.
    • On this page, you'll find your newly created API key.
  5. Use the API key for authentication:

    • The API key will look like this: secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
    • You'll use this key to authenticate your requests to the NeverBounce API.

What can you do with the NeverBounce API?

Based on the search results provided, here is a summary of the data models you can interact with using the NeverBounce API:

Email Validation

  • Single Email Verification:

    • Verify individual email addresses in real-time [1]
    • Check syntax, domain validity, and mailbox existence [5]
  • Bulk Email Validation:

    • Upload and verify large lists of email addresses [5]
    • Process CSV files or directly supply data via API [4]

Job Management

  • Create Jobs:

    • Start new bulk verification jobs [4]
    • Specify input data source (uploaded file or direct input)
    • Set job parameters like auto-parse and auto-start [4]
  • Check Job Status:

    • Poll the API to check the progress of running jobs [4]
    • Get information on job completion, errors, etc.
  • Retrieve Results:

    • Download verified results once a job is complete [4]
    • Access detailed verification outcomes for each email

List Management

  • Automated List Cleaning:
    • Set up automated verification of existing contact lists [5]
    • Schedule regular cleaning of email databases

Real-time Verification

  • API Integration:

    • Verify emails in real-time as they are collected [5]
    • Integrate verification into forms and sign-up processes
  • JavaScript Widget:

    • Client-side verification option for web applications [1]

Account Management

  • API Key Management:

    • Authenticate and authorize API requests [1]
  • Usage Tracking:

    • Monitor API usage and credit consumption

Integrations

  • Platform Connections:
    • Integrate with email marketing platforms like Mailchimp, HubSpot, etc. [5]
    • Connect to CRM systems and other business tools

Key Points to Consider:

  • NeverBounce offers a RESTful API with responses in JSON format [1]
  • Multiple API wrappers are available for different programming languages [1][4]
  • The API supports both single email verification and bulk list processing [4][5]
  • Real-time verification can be implemented through API calls or a JavaScript widget [1][5]
  • Comprehensive job management features allow for handling large-scale verification tasks [4]
  • Integration capabilities extend the API's functionality to various marketing and business platforms [5]

NeverBounce's API provides a versatile set of data models and endpoints to cover various email verification needs, from individual checks to large-scale list management and integration with existing systems.