Tomba

The Tomba API provides programmatic access to email discovery, verification, enrichment, and company intelligence workflows. Find professional emails, validate deliverability, retrieve sources, and automate prospecting at scale using simple REST endpoints.

Getting Started

To begin, send authenticated requests using your API credentials in the request headers. Start with domain search or email finder, then verify addresses and enrich contacts as needed for your workflow.

Code
curl -X GET 'https://api.tomba.io/v1/email-finder?domain=tomba.io&first_name=emily&last_name=harris' \
  -H "X-Tomba-Key: your_api_key" \
  -H "X-Tomba-Secret: your_api_secret"

Rate Limits

Rate limits are enforced per endpoint and per plan across three dimensions: per-second (rps), per-minute (rpm), and per-day. Your daily limit equals your monthly credits divided by 5.

All plans with 50,000+ credits (Pro Plus, Enterprise, Scale, PAYG 50k+) have no rate limits. Full details at Rate Limits. Upgrade your plan for higher throughput.

Rate Limit Headers

Each API response includes these headers:

• RateLimit-Policy: Rate limit policies with quota and window (e.g. "rps";q=8;w=1, "daily";q=4000;w=86400)
• RateLimit: Remaining quota and time until reset (e.g. "rps";r=7;t=1, "daily";r=3842;t=64802)
• x-second-rate-limit: Total per-second request limit
• x-minute-rate-limit: Total per-minute request limit
• x-daily-rate-limit: Total daily request limit
• x-minute-request-left: Remaining requests for the minute
• x-daily-request-left: Remaining requests for the day
• x-minute-reset-seconds: Seconds until minute limit resets
• x-daily-reset-seconds: Seconds until daily limit resets
• Retry-After: Seconds to wait (on 429 responses only)

When any limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Check Your Usage

Use GET /v1/rate-limits to see your current usage per endpoint.

Authentication

All endpoints require both authentication headers: X-Tomba-Key and X-Tomba-Secret.

Credential failures return 401 Unauthorized with an errors.type of authentication_failed, or api_key_expired for a key past its expiry date. 400 Bad Request is reserved for requests that authenticate but are rejected by a parameter or plan rule. Branch on errors.type, not on the status code alone. See Error Handling for the full list.

Versioning

The current stable API base URL is https://api.tomba.io/v1. Backward-compatible improvements may be released without changing the major version path.

Performance

Recommended client timeout: 180 seconds. Searches run in real time against live infrastructure — response times vary with the target company's SMTP server speed, website responsiveness, and the depth of catch-all detection. Set generous timeouts and use asynchronous calls or bulk endpoints for high-volume workflows.

Support

For questions, troubleshooting, or integration help, contact support at info@tomba.io or visit the documentation at https://docs.tomba.io.

MCP Server

Tomba also provides a Model Context Protocol (MCP) server for AI assistants. Connect Claude, ChatGPT, Cursor, VS Code, and other AI tools to Tomba's data via the standardized MCP protocol at https://mcp.tomba.io/mcp.

The MCP server supports three authentication methods:

• OAuth 2.0 (Recommended for Claude Desktop) — auto-discovers endpoints and opens a browser for authorization
• Bearer Token — Base64-encode your credentials as apiKey:secretKey:

  Code
  Authorization: Bearer base64(apiKey:secretKey)

• API Key Headers — pass credentials directly:

  Code
  X-Tomba-Key: your_api_key
  X-Tomba-Secret: your_api_secret

Get your API credentials at app.tomba.io/api.