Copy page

SDKs

Rust SDK

The tomba crate is the official Rust client for the Tomba API. All methods hang off one blocking client, and each method sends one request.

Requirements

• Rust 1.85 or later. Cargo.toml declares rust-version = "1.63", but the current releases of the crate's dependencies (reqwest 0.12 and the crates it pulls in) need Rust 1.85.
• On Linux, OpenSSL development headers, for reqwest's default TLS backend.

Install

Code
cargo add tomba

The client uses reqwest::blocking, so each call blocks the current thread. In async code, run calls with tokio::task::spawn_blocking.

Authenticate

Create an API key and copy your secret on the API keys page, then export both:

Code
export TOMBA_API_KEY="ta_xxxx"
export TOMBA_SECRET_KEY="ts_xxxx"

The SDK doesn't read environment variables. Pass the values in a TombaConfig to Tomba::init, and the client sends them as the X-Tomba-Key and X-Tomba-Secret headers. Key expiry and rotation are covered in Authentication.

First request

Find the email address of a person at a company:

Code
use std::env;

use tomba::{Tomba, TombaConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Tomba::init(TombaConfig {
        key: env::var("TOMBA_API_KEY")?,
        secret: env::var("TOMBA_SECRET_KEY")?,
    })?;

    let result = client.email_finder("stripe.com", "Jane", "Doe", None)?;
    if let Some(email) = result.data["data"]["email"].as_str() {
        println!("{email}");
    }
    Ok(())
}

Every method returns Result<TombaResponse, TombaError>. TombaResponse.data is the JSON body as a serde_json::Value, and TombaResponse.rate_limit holds the rate limit headers. The API wraps its payload in its own data object (Response format), so the address is at result.data["data"]["email"].

Errors

TombaError has four variants:

Code
use std::env;

use tomba::{Tomba, TombaConfig, TombaError};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Tomba::init(TombaConfig {
        key: env::var("TOMBA_API_KEY")?,
        secret: env::var("TOMBA_SECRET_KEY")?,
    })?;

    match client.email_finder("stripe.com", "Jane", "Doe", None) {
        Ok(result) => println!("{}", result.data["data"]["email"]),
        Err(TombaError::Api { code, message }) => eprintln!("HTTP {code}: {message}"),
        Err(err) => eprintln!("{err}"),
    }
    Ok(())
}

To branch on errors.type, parse message with serde_json::from_str. Each type is described in Errors.

Rate limits and retries

The SDK doesn't retry. result.rate_limit holds the response's rate limit headers as Option<String> fields: x_second_rate_limit, x_minute_rate_limit, x_daily_rate_limit, x_minute_request_left, x_daily_request_left, x_minute_reset_seconds, x_daily_reset_seconds, retry_after, rate_limit_policy, and rate_limit. tomba::parse_rate_limit reads the same headers from a reqwest::header::HeaderMap.

A 429 returns TombaError::Api with code 429 and no headers. Wait before retrying as described in Handle 429 responses.

Requests time out after 120 seconds; the timeout isn't configurable.

Method reference

All methods are on Tomba, the value returned by Tomba::init, and return Result<TombaResponse, TombaError>. Request bodies are &serde_json::Value.

bulk_type is the {type} segment listed in Bulk types; the order of calls is described in Lifecycle. create_bulk sends a JSON body, so it can't create jobs that need a CSV upload, such as email finder jobs.

Source

github.com/tomba-io/rust (Apache-2.0).