Copy page

SDKs

C# SDK

The Tomba NuGet package is the official .NET client for the Tomba API. Each API area is a service class, and each method sends one request and returns the raw HttpResponseMessage.

Requirements

• .NET 10. Version 1.0.1 of the package targets net10.0 only.
• Newtonsoft.Json, installed as a dependency.

Install

Code
dotnet add package Tomba

The classes are in the Tomba namespace.

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 to SetKey() and SetSecret(), and the client sends them as the X-Tomba-Key and X-Tomba-Secret headers. Call each setter once per client: a second call throws ArgumentException. Key expiry and rotation are covered in Authentication.

First request

Verify an email address.

Code
using Newtonsoft.Json.Linq;
using Tomba;

var client = new Client()
    .SetKey(Environment.GetEnvironmentVariable("TOMBA_API_KEY"))
    .SetSecret(Environment.GetEnvironmentVariable("TOMBA_SECRET_KEY"));

var response = await new Verifier(client).EmailVerifier("jane.doe@stripe.com");
var body = JObject.Parse(await response.Content.ReadAsStringAsync());
Console.WriteLine(body["data"]?["email"]?["status"]);

The example is a dotnet new console program with top-level statements. Methods return the HttpResponseMessage unparsed, so read and parse the JSON body yourself. The API wraps its payload in a data object (Response format); the verification status is at data.email.status.

Errors

The SDK throws TombaException when the API responds with status 400 or higher and when the request fails. For API errors, the exception is wrapped: the outer TombaException has the API's errors.message as Message, and its InnerException is a TombaException whose Code is the HTTP status and whose Response is the raw response body.

Code
using Newtonsoft.Json.Linq;
using Tomba;

var client = new Client()
    .SetKey(Environment.GetEnvironmentVariable("TOMBA_API_KEY"))
    .SetSecret(Environment.GetEnvironmentVariable("TOMBA_SECRET_KEY"));

try
{
    var response = await new Verifier(client).EmailVerifier("jane.doe@stripe.com");
    var body = JObject.Parse(await response.Content.ReadAsStringAsync());
    Console.WriteLine(body["data"]?["email"]?["status"]);
}
catch (TombaException e)
{
    var inner = e.InnerException as TombaException;
    Console.WriteLine($"{inner?.Code} {e.Message}");
    Console.WriteLine(inner?.Response);
}

inner is null when the request failed before a response arrived. The raw Response is the JSON error body; each errors.type in it is described in Errors.

Rate limits and retries

The SDK doesn't retry. Client.ParseRateLimit(response) reads the rate limit headers of a successful response into a RateLimit with the int? properties SecondRateLimit, MinuteRateLimit, DailyRateLimit, MinuteRequestLeft, DailyRequestLeft, MinuteResetSeconds, DailyResetSeconds, and RetryAfter, and the string properties RateLimitPolicy and RateLimitValue.

A 429 throws TombaException without the response headers. Wait before retrying as described in Handle 429 responses.

Requests time out after 120 seconds.

Method reference

Create each service with the client, for example new Verifier(client). Every method returns Task<HttpResponseMessage>.

type is the {type} segment listed in Bulk types. CreateAsync 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/csharp (Apache-2.0). Release notes are in CHANGELOG.md.