ZeroBounce Getting Started: API Key & First Request (2026)

Getting started overview

Integrating with ZeroBounce involves a sequence of steps designed to enable email validation functionality within an application. The core process includes account creation, API key retrieval, and the execution of an initial API call. ZeroBounce provides an API v2 reference that details available endpoints and response structures. The platform's primary function is to verify email addresses, reducing bounce rates and improving deliverability for marketing and transactional emails. The API supports real-time validation for individual emails and bulk processing for larger lists.

Developers can interact with the ZeroBounce API directly via HTTP requests or utilize one of the officially supported SDKs for languages such as Python, Node.js, PHP, Java, and .NET. These SDKs abstract away the complexities of HTTP requests, authentication, and response parsing, offering language-specific methods for common operations.

Quick Reference Table

Create an account and get keys

Before making any API calls, you must register for a ZeroBounce account. This process establishes your user profile and provides access to your API key, which is essential for authenticating requests.

Account Registration

1. Navigate to the official ZeroBounce registration page.
2. Provide the required information, including your name, email address, and a password.
3. Agree to the terms of service and privacy policy.
4. Complete any email verification steps if prompted.

Upon successful registration, you will be granted 100 free credits per month, which can be used for testing and initial validation tasks.

API Key Retrieval

Your API key serves as the credential for authenticating your application's requests to the ZeroBounce API. It should be kept confidential and never exposed in client-side code or public repositories.

1. Log in to your ZeroBounce account.
2. From the dashboard, navigate to the API section. Depending on UI updates, this might be under a menu like "API Settings" or directly visible.
3. Locate your unique API key. ZeroBounce typically displays it prominently.
4. Copy the API key. It is a long alphanumeric string.

ZeroBounce employs API keys for authentication, a common method for controlling access to web services. For enhanced security, consider environment variables or secure credential management systems to store your API key, especially in production environments, as recommended by general API key security practices.

Your first request

With your API key in hand, you can now make your first email validation request. This example demonstrates validating a single email address using the primary email validation endpoint. We will show examples using curl for direct HTTP requests and a Python SDK example for a higher-level abstraction.

API Endpoint

The main endpoint for validating a single email address is:

GET https://api.zerobounce.net/v2/validate

This endpoint requires two query parameters: api_key and email. Optionally, an ip_address parameter can be included for more accurate validation, particularly for identifying emails associated with specific user registrations.

Example with curl (HTTP GET Request)

Replace YOUR_API_KEY with your actual ZeroBounce API key and [email protected] with the email address you wish to validate. The ip_address can be omitted if not relevant, or set to 127.0.0.1 for a generic local IP.

curl -X GET \
  'https://api.zerobounce.net/v2/validate?api_key=YOUR_API_KEY&[email protected]&ip_address=127.0.0.1'

Expected curl Response (JSON)

A successful response will return a JSON object containing validation details. The status field indicates the validation result (e.g., valid, invalid, catch-all).

{
  "address": "[email protected]",
  "status": "valid",
  "sub_status": "",
  "free_email": true,
  "did_you_mean": null,
  "account": "test",
  "domain": "example.com",
  "domain_age_days": "7235",
  "smtp_provider": "",
  "mx_found": "true",
  "mx_record": "example.com",
  "firstname": "",
  "lastname": "",
  "gender": "",
  "city": "",
  "region": "",
  "zipcode": "",
  "country": "",
  "processed_at": "2026-05-29 10:30:00.000"
}

Example with Python SDK

First, install the ZeroBounce Python SDK:

pip install zerobounce

Then, use the following Python code. Replace YOUR_API_KEY and [email protected] as before:

import zerobounce

# Configure your API key
zerobounce.api_key = "YOUR_API_KEY"

def validate_email_address(email_address, ip_address="127.0.0.1"):
    try:
        response = zerobounce.validate(email_address, ip_address)
        print(f"Email: {response['address']}")
        print(f"Status: {response['status']}")
        print(f"Sub Status: {response['sub_status']}")
        print(f"Free Email: {response['free_email']}")
        # Print other relevant fields as needed
        return response
    except zerobounce.exceptions.ZeroBounceException as e:
        print(f"ZeroBounce API Error: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

# Call the validation function
validation_result = validate_email_address("[email protected]", "127.0.0.1")
if validation_result:
    print("\nFull Response:")
    for key, value in validation_result.items():
        print(f"  {key}: {value}")

Common next steps

After successfully validating your first email, several common next steps can enhance your integration and leverage more of ZeroBounce's capabilities:

1. Integrate into Application Logic: Incorporate the email validation API call into your application's user registration, lead capture, or data import workflows. This can prevent invalid emails from entering your system from the outset.
2. Handle All Statuses: Review the ZeroBounce API response fields documentation to understand all possible status and sub_status values. Implement logic in your application to handle different validation outcomes appropriately (e.g., rejecting invalid emails, flagging catch-all for manual review, or accepting valid ones).
3. Explore Bulk Validation: For existing email lists, utilize ZeroBounce's bulk email validation API. This typically involves uploading a CSV file and retrieving results asynchronously.
4. Utilize Data Enrichment: Beyond validation, ZeroBounce offers data enrichment features, such as appending gender, name, and location data to valid email addresses. Explore the data enrichment endpoints to enhance your user profiles.
5. Monitor API Usage: Keep track of your credit usage and API calls through your ZeroBounce dashboard to manage costs and ensure uninterrupted service.
6. Implement Webhooks: For asynchronous processes like bulk validation, consider setting up webhooks to receive notifications when results are ready, rather than polling the API. This improves efficiency and reduces API call volume.
7. Review SDKs: If you are not using an SDK, consider adopting one for your preferred programming language. SDKs often simplify API interaction, error handling, and authentication, as outlined in the ZeroBounce SDK documentation.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps for ZeroBounce API requests:

1. Invalid API Key

• Symptom: API returns an error message like "Invalid API Key" or "Authentication Failed".
• Resolution: Double-check that you have copied your API key correctly from your ZeroBounce dashboard. Ensure there are no leading or trailing spaces. API keys are case-sensitive.

2. Missing Required Parameters

• Symptom: API returns an error indicating a missing parameter, e.g., "Missing email parameter".
• Resolution: Verify that both api_key and email parameters are correctly included in your request URL for the /v2/validate endpoint. For other endpoints, consult the API reference for required parameters.

3. Insufficient Credits

• Symptom: API returns an error related to credit limits, such as "Insufficient credits".
• Resolution: Check your credit balance in your ZeroBounce account. If you've used your free credits, you may need to purchase additional credits to continue.

4. Network Connectivity Issues

• Symptom: Your application reports connection timeouts or network errors before receiving an API response.
• Resolution: Verify your internet connection. If you are behind a firewall or proxy, ensure that outbound connections to api.zerobounce.net are permitted.

5. Incorrect Endpoint or HTTP Method

• Symptom: API returns a 404 Not Found or 405 Method Not Allowed error.
• Resolution: Confirm that you are using the correct endpoint URL (e.g., https://api.zerobounce.net/v2/validate) and the appropriate HTTP method (GET for validation, as per the ZeroBounce documentation).

6. SDK-Specific Errors

• Symptom: Errors originating from the SDK itself, such as incorrect method calls or configuration issues.
• Resolution: Refer to the specific ZeroBounce SDK documentation for your language. Ensure the SDK is installed correctly and configured with your API key before making calls.

7. IP Address Parameter

• Symptom: Validation results seem less accurate or some emails are flagged unexpectedly.
• Resolution: While optional, providing an accurate ip_address can improve validation accuracy by allowing ZeroBounce to check for IP-specific reputation or behaviors. If you are validating emails collected from users, pass the user's IP address. If not available, 127.0.0.1 is a common placeholder, but understand its limitations.

If you continue to experience issues, ZeroBounce provides extensive FAQ documentation and a support team that can assist with specific integration problems.