Tomba email finder Getting Started: API Keys & First Request (2026)

Getting started overview

Integrating with the Tomba email finder API involves a sequence of steps, beginning with account creation and credential generation, followed by making an authenticated request. The Tomba API is RESTful, supporting standard HTTP methods and JSON payloads for requests and responses Tomba API documentation. Developers can utilize one of the officially supported SDKs or interact directly with the API endpoints.

This guide focuses on the essential steps required to get your first API call working, covering account setup, API key retrieval, and an example request using the Python SDK. While Tomba offers multiple core products, the initial request example will demonstrate the basic email finding capability.

Here's a quick reference for the setup process:

Create an account and get keys

To access the Tomba API, you must first create an account. Tomba offers a free tier that includes 25 search requests and 50 email verifications per month, which is suitable for initial testing and development.

1. Register for an account: Navigate to the Tomba registration page and complete the signup process. You will typically be asked for an email address and password.
2. Access the API Dashboard: After logging in, go to your API Keys section within the Tomba dashboard.
3. Retrieve API Key and Secret Key: On this page, you will find your unique API Key and Secret Key. These two values are essential for authenticating your API requests. It is recommended to store these credentials securely, for instance, by using environment variables in your development setup rather than hardcoding them directly into your application. Best practices for API key management often involve using secret management services or environment variables to prevent accidental exposure Google Cloud API Key best practices.

Keep these keys confidential. If you suspect your keys have been compromised, you can regenerate them from the same API Keys section in your Tomba dashboard.

Your first request

This section demonstrates how to make a basic API request to Tomba using the Python SDK to find emails associated with a specific domain. Ensure you have Python installed and then install the Tomba Python SDK.

Install the Python SDK

pip install tomba

Configure and make a request

Replace YOUR_API_KEY and YOUR_API_SECRET with the credentials obtained from your Tomba dashboard. This example performs a domain search for stripe.com to retrieve email addresses associated with that domain.

import os
from tomba.client import TombaClient

# It is recommended to load API keys from environment variables
# rather than hardcoding them.
api_key = os.getenv('TOMBA_API_KEY', 'YOUR_API_KEY')
api_secret = os.getenv('TOMBA_API_SECRET', 'YOUR_API_SECRET')

# Initialize the Tomba client
tomba = TombaClient(api_key, api_secret)

try:
    # Perform a Domain Search
    # For more details on parameters, refer to the Tomba API documentation:
    # https://tomba.io/docs/api#domain-search
    domain_result = tomba.domain_search('stripe.com')

    print("Domain Search Result for stripe.com:")
    if domain_result and 'data' in domain_result and domain_result['data']:
        print(f"Domain: {domain_result['data']['domain']}")
        print(f"Total Emails: {domain_result['data']['total']}")
        for email in domain_result['data']['emails']:
            print(f"  - Email: {email['value']}, Type: {email['type']}, Seniority: {email['seniority']}")
    else:
        print("No data found for the domain.")

except Exception as e:
    print(f"An error occurred: {e}")

Executing this code will output a list of email addresses found for stripe.com, along with their types and seniorities, demonstrating a successful interaction with the Tomba API.

Common next steps

Once you have successfully made your first API call, you can explore other functionalities and refine your integration:

• Explore other API endpoints: Tomba offers various endpoints beyond domain search, including Email Finder (by name and domain), Email Verifier, and Bulk Email Finder. Each serves different use cases for lead generation and contact enrichment.
• Implement error handling: Integrate robust error handling into your application to manage API rate limits, invalid requests, or other potential issues. The Tomba API returns standard HTTP status codes and JSON error messages Tomba error handling documentation.
• Utilize webhooks: For Asynchronous operations or notifications, consider implementing webhooks. This allows Tomba to notify your application of events, such as the completion of a bulk processing job, instead of continuous polling.
• Review pricing and usage: Monitor your API usage from the Tomba dashboard and review the pricing plans to ensure your current plan accommodates your expected volume.
• Explore other SDKs: If Python is not your primary development language, consider using one of the other officially supported SDKs for PHP, Node.js, Ruby, Go, Java, or Rust to integrate Tomba into your projects.

Troubleshooting the first call

If your initial API call encounters issues, consider the following common troubleshooting steps:

• Check API Keys: Verify that your API Key and Secret Key are correctly copied from your Tomba dashboard and accurately configured in your code. Typos or incorrect values are frequent causes of authentication failures.
• Review Authentication Method: Ensure that your request headers are correctly formatted with your API credentials as specified in the Tomba API authentication guide. The Python SDK handles this automatically, but direct HTTP requests require careful header construction.
• Verify Base URL: Confirm that you are sending requests to the correct base URL for the Tomba API, which is https://api.tomba.io/v1.
• Examine Error Messages: The Tomba API provides detailed error messages in its JSON responses. Carefully read these messages, as they often pinpoint the exact problem (e.g., invalid parameters, rate limit exceeded, missing required fields). The Tomba error codes documentation provides a comprehensive list of potential errors and their meanings.
• Check Rate Limits: If you are making numerous requests in a short period, you might hit API rate limits. The free tier and paid plans have different limits. Check your usage in the Tomba dashboard and consult the rate limits documentation.
• Consult SDK Documentation: If using an SDK, refer to its specific documentation for common pitfalls or configuration details. Issues might arise from incorrect SDK usage rather than the API itself.
• Network Connectivity: Ensure your development environment has stable internet connectivity and no firewall rules are blocking outbound HTTPs requests to api.tomba.io.