API Documentation

Overview of No2bounce API

The no2bounce API is designed to provide a robust solution for email validation, helping businesses ensure the accuracy and deliverability of their email lists. This API is an essential part of the no2bounce application, allowing users to programmatically validate large volumes of email addresses in real time.

To enhance ease of use, the no2bounce API is accessible via the POST method, making it straightforward for developers to incorporate real-time email validation into their applications. With just a single endpoint, you can instantly verify the validity of an email address, ensuring that only accurate and deliverable emails are accepted.
‍
The real-time lookup API from no2bounce provides a reliable and efficient solution for email verification needs. By integrating this tool into your application, you can significantly improve the quality of your data, reduce bounce rates, and enhance the overall user experience. Whether you’re onboarding new users or maintaining a clean email list, no2bounce makes real-time email verification simple and effective.

API Concepts

1.Accessing the API

1.1 Login to Your Account

Log in to your account using your credentials.
‍Locate the API Menu: On the left side of the menu bar, you will find the API menu.

1.2 Navigate to the API Menu

Click on the API Menu: Once clicked, the API management page will appear.
Initial State: The API page will initially be empty as shown below.

2.Creating an API

2.1 Steps to Create an API

Click on Create API: You will see a "Create API" button; click on it.
Enter API Details: A popup will appear prompting you to enter the following details:
Enter API Details: This must be unique across your account.
Email Limit: This is the fixed number of emails that this API can process. Note that this allocation does not deduct from your overall credit balance; credits are only consumed upon actual usage.

2.2 API Token Details

Token: Each API will generate a unique hash key that serves as the API token.
Validity: The token comes with a startDate and endDate, specifying the period it is active.
Usage Metrics: You can monitor the allocated limit and the consumed usage for each API.

3.Making API Requests

3.1 Request Format

To make a request to the API, use the following curl command:

curl --location 'https://connect.no2bounce.com/n2b_apiValidator' \
      --header 'apitoken: 0b5f6948f5aa7dbfdac5ded92ae2623f' \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "emailList": [
          "demo@gmail.com",
          "demo1@outlook.com",
          "demo2@yahoo.com"
        ],
        "catchall": true,
        "hashkey": "uniqueStringHere"
      }'

💡 The hashkey is used to prevent duplicate requests during bulk email validation, particularly when processing large datasets of over 40,000 emails. Based on customer feedback, some users experienced delays of several seconds during the validation process. This caused instances where customers clicked multiple times within a short span (less than 1 second), resulting in credit loss due to duplicate requests.To mitigate this issue, you can pass any unique string as the hashkey. Each key has a validity of 3 minutes, ensuring that subsequent requests within this timeframe are ignored, effectively preventing duplicate processing.

3.2 Request Details

API Endpoint: https://connect.no2bounce.com/n2b_apiValidator
Method: POST
Headers:
apitoken: The unique token generated for your API.
Content-Type: Set to application/json.
Body: JSON object containing the emailList parameter:
emailList: An array of email addresses. The minimum number of emails is 1, and there is no upper limit.
Body: JSON object containing the emailList parameter:
emailList: An array of email addresses. The minimum number of emails is 1, and there is no upper limit.

3.3 Response

Tracking ID: Upon processing the request, the API will return a unique trackingId in the response, which is used for tracking and retrieving the results.

{
    "message": "Success",
    "statusCode": 200,
    "data": {
        "trackingId": 1724302650843,
    }
}

4.Validating the Result

4.1 Result Validation

Curl Command

curl --location 'https://connect.no2bounce.com/n2b_apiValidatorResult?trackingId=1724302092064'\
    --header 'apitoken:0b5f6948f5aa7dbfdac5ded92ae2623f'

4.2 Validation Details

API Endpoint: https://connect.no2bounce.com/n2b_apiValidatorResult
Method: GET
Headers:
apitoken: The unique token generated for your API.
Query Parameters:
trackingId: The unique ID returned when the API was initially called.

4.3 Response

The API will return processing information, including a final result named apiResponse once the validation is complete.

{
    "message": "Success",
    "statusCode": 200,
    "data": {
        "taskId": 1724302650843,
        "totalEmails": 20005,
        "completedEmails": 1915,
        "deliverability": 142,
        "catchAll": 1456,
        "invalid": 317,
        "bounce": 0,
        "spam": 0
    }
}

5.Viewing and Downloading Results Through UI and API

5.1 Viewing Results through UI

Usage Report: The results can be viewed directly from the UI in a table format.
View Button: Click the "View" button to display the live progress of the API processing.

Download Button: Once processing is complete, a "Download" button will appear, allowing you to download the results as a CSV file.

5.2 Viewing Results through API

API Validator Response Types:
When you hit the API validator, you will receive one of three types of responses based on the status of the email validation process. Below are the details for each type of response:

5.2.1 In-Progress Response

When the validation process is still ongoing, you will receive a progress update. Here is an example of such a response:

{
    "message": "Success",
    "statusCode": 200,
    "data": {
        "taskId": 1724302650843,
        "totalEmails": 20005,
        "completedEmails": 1915,
        "deliverability": 142,
        "catchAll": 1456,
        "invalid": 317,
        "bounce": 0,
        "spam": 0
    }
}

5.2.2 Final Report for Email Count Greater Than 20K

you will receive a signed URL to download the final report. Here is an example:

{
    "message": "Success",
    "statusCode": 200,
    "data": {
        "catchall_status": "Completed",
        "signedUrl": "https://connect.no2bounce.com/n2b_apiValidator/generatorResult/1727095008289_catchall.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA3W2VPMD3YV5O3XNP%2F20240923%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240923T123947Z&X-Amz-Expires=3600&X-Amz-Signature=38ad24d83d7dcb6eca6cd126676586ce739a67d0d6a875b0122cc0423ae0922c&X-Amz-SignedHeaders=host&x-id=GetObject"
    }
}