---
title: SDK .NET
description: "Envoyez des e-mails, gérez une boîte de réception, vérifiez des webhooks en .NET avec le package BillionSend : toute l'API, nouvelles tentatives, idempotence."
ai:
  exclude: true
---

Le package `BillionSend` est le client BillionSend pour .NET. Il couvre toutes les opérations de la [référence de l'API](/docs/fr/api-reference) : envoi, domaines, contacts, campagnes, templates, webhooks, boîtes de réception avec leurs fils de discussion et leurs brouillons, événements de boîte de réception en direct et inscription des agents. Le code source est sur GitHub : [billionsend/billionsend-dotnet](https://github.com/billionsend/billionsend-dotnet).

## Installer

Nécessite .NET 8 ou une version plus récente. Le package n'a aucune dépendance en dehors du runtime .NET : il utilise `HttpClient` et `System.Text.Json`.

```sh
dotnet add package BillionSend --version 0.1.0
```

## Envoyer un e-mail

```csharp
using BillionSend;

using var client = new BillionSendClient(); // reads BILLIONSEND_API_KEY

var sent = await client.Emails.SendAsync(
    new
    {
        from = "Acme <hello@acme.dev>",
        to = new[] { "success@simulator.amazonses.com" },
        subject = "Welcome to Acme",
        html = "<p>Glad you are here.</p>",
    },
    new IdempotentRequestOptions { IdempotencyKey = "welcome/ana" });

Console.WriteLine(sent?["id"]);
```

`new BillionSendClient("bs_...")` prend la clé directement, et `new BillionSendClient(new BillionSendOptions { ... })` règle le reste : `ApiKey`, `BaseUrl`, `Timeout` (par tentative, 60 secondes par défaut), `MaxRetries`, `HttpClient` (le vôtre, issu par exemple d'`IHttpClientFactory`, que le client ne libère alors pas et dont le `BaseAddress` est ignoré), `Headers` (envoyés avec chaque requête) et `JsonSerializerOptions`. `BILLIONSEND_BASE_URL` remplace l'URL de l'API. Un même client peut être partagé sans risque entre plusieurs threads : créez-le une seule fois et gardez-le pendant toute la vie de l'application.

## Noms des méthodes

Chaque opération est une méthode asynchrone qui porte le nom de son identifiant dans la [référence de l'API](/docs/fr/api-reference), le chemin séparé par des points devenant une chaîne de ressources en PascalCase avec le suffixe `Async` : `emails.send` devient `client.Emails.SendAsync`, `emails.receiving.attachments.list` devient `client.Emails.Receiving.Attachments.ListAsync`, et `agent.claimEmail` devient `client.Agent.ClaimEmailAsync`. `emails.metrics` devient `client.Emails.Metrics.GetAsync`, à côté de `LinksAsync`, `CountriesAsync` et `ClientsAsync`.

Une méthode prend, dans l'ordre, les paramètres de chemin, le corps de la requête, les paramètres de requête sous forme de `Dictionary<string, object?>`, les options de l'appel et un `CancellationToken`. Un corps peut être tout objet que `System.Text.Json` sait écrire : un objet anonyme, un dictionnaire, un `JsonNode` ou un type de votre cru, dont les noms de propriété sont écrits en snake_case (`ReplyTo` devient `reply_to`). Les listes des paramètres de requête sont séparées par des virgules, les booléens s'écrivent `true` et `false`, et les valeurs `null` sont omises. Les réponses sont le corps JSON analysé, sous forme de `JsonNode?`, avec les noms de champ de l'API elle-même (`sent?["id"]`) : la référence de l'API les décrit donc champ par champ, et `answer.Deserialize<T>()` en lit une dans votre propre type.

```csharp
var page = await client.Emails.Receiving.ListAsync(new Dictionary<string, object?>
{
    ["limit"] = 20,
    ["unread"] = "true",
});

foreach (var email in page!["data"]!.AsArray())
{
    Console.WriteLine($"{email!["from"]}: {email["subject"]}");
}
```

## Idempotence et nouvelles tentatives

Les huit opérations d'envoi (`Emails.SendAsync`, `Emails.BatchAsync`, `ReplyAsync` et `ForwardAsync` d'un e-mail reçu, `Inboxes.SendAsync`, `Inboxes.Drafts.SendAsync`, `ReplyAsync` et `ForwardAsync` d'un fil de discussion) envoient toujours un `Idempotency-Key`. Sans `IdempotencyKey` dans leurs `IdempotentRequestOptions`, chaque appel en génère une (un UUID) que ses nouvelles tentatives réutilisent : une nouvelle tentative après un délai dépassé n'envoie donc jamais deux fois. Votre propre clé rend aussi sûre une répétition venue d'un autre processus, et une répétition avec la même clé et le même corps renvoie la première réponse.

Les échecs qui méritent une nouvelle tentative sont retentés deux fois par défaut : 429, 5xx, délais dépassés, erreurs réseau, et le `409 concurrent_idempotent_requests` renvoyé tant que la première tentative avec la même clé est encore en cours. Seules les requêtes sans danger à répéter sont retentées : `GET`, `PUT`, `DELETE` et les opérations d'envoi. Le client attend ce que demande `Retry-After` (en secondes ou sous forme de date HTTP) et lève l'exception immédiatement lorsqu'il demande plus d'une minute ; sinon il espace les tentatives de façon exponentielle, de 0,5 s à 8 s, avec de la gigue. `MaxRetries` et `Timeout` se règlent sur le client et peuvent être remplacés pour un seul appel dans ses options (`new IdempotentRequestOptions { MaxRetries = 0 }`) ; un flux d'événements n'est chronométré que jusqu'à son ouverture.

## Erreurs

Un appel qui échoue lève `ValidationException` (400, 422), `AuthenticationException` (401, ou aucune clé configurée, avec `Name` valant `missing_api_key` avant tout envoi), `PermissionDeniedException` (403), `NotFoundException` (404), `ConflictException` (409), `RateLimitException` (429, avec `RetryAfter` en secondes), `ApiException` (5xx), `ApiConnectionException` (aucune réponse : échec DNS, de connexion ou TLS) ou `ApiTimeoutException` (la tentative a dépassé son délai, un cas particulier de `ApiConnectionException`). Toutes sont dans l'espace de noms `BillionSend` et étendent `BillionSendException`, levée telle quelle pour tout autre statut, avec `StatusCode` (`null` en l'absence de réponse), `Name` (le nom de l'erreur dans l'API), `Message` et `RequestId`, le `x-request-id` de la réponse, qui est l'identifiant de la requête dans la page Journaux du tableau de bord. Annuler le `CancellationToken` lève une `OperationCanceledException`, comme partout en .NET.

```csharp
try
{
    var email = await client.Emails.GetAsync(id);
}
catch (NotFoundException)
{
    // no such email
}
catch (BillionSendException error)
{
    Console.WriteLine($"{error.StatusCode} {error.Name}: {error.Message} (request {error.RequestId})");
    throw;
}
```

## Listes

Les méthodes de liste renvoient une page. Chaque liste à curseur dispose aussi d'une méthode `ListAllAsync` (`SearchAllAsync` pour la recherche de fils) qui renvoie un `IAsyncEnumerable<JsonNode>`, allant chercher les pages suivantes au fur et à mesure de la lecture, en remontant lorsque `before` est défini :

```csharp
await foreach (var contact in client.Contacts.ListAllAsync(new Dictionary<string, object?> { ["limit"] = 100 }))
{
    Console.WriteLine(contact["email"]);
}
```

## La boîte de réception d'un agent

Attendez les nouveaux e-mails sur le [flux d'événements](/docs/fr/inboxes) et répondez dans leur fil :

```csharp
const string inboxId = "support@acme.dev"; // an inbox id or its address

await using var events = await client.Inboxes.Events.StreamInboxAsync(
    inboxId,
    new Dictionary<string, object?> { ["types"] = "inbox.email.received" });

await foreach (var item in events)
{
    if (item is StreamGapEvent)
    {
        continue; // events may be missing: read the threads again
    }

    var ids = ((InboxStreamEvent)item).Payload;
    var threadId = (string?)ids?["thread_id"];
    var emailId = (string?)ids?["email_id"];
    if (threadId is null || emailId is null)
    {
        continue;
    }

    await client.Inboxes.Threads.Emails.ReplyAsync(
        inboxId,
        threadId,
        emailId,
        new { text = "Thanks, we are on it." },
        new IdempotentRequestOptions { IdempotencyKey = $"reply/{emailId}" });
}
```

`StreamInboxAsync` rend la main une fois le flux ouvert, ou lève l'erreur qui l'a refusé, et donne un `EventStream` à lire avec `await foreach`. Un `InboxStreamEvent` a `Id`, `Event` (le nom de l'événement de webhook, comme `inbox.email.received`), `Data` (les champs `type`, `created_at`, `inbox_id` et `data` de la charge utile du webhook) et `Payload`, le `data` interne avec les identifiants à lire ensuite. Le flux se reconnecte avec `Last-Event-ID` lorsque la connexion tombe et rejoue ce qu'il a manqué ; gardez `stream.LastEventId` et repassez-le comme `LastEventId` dans `new EventStreamOptions { ... }` pour reprendre après un redémarrage. Un `StreamGapEvent` arrive une seule fois lorsque le flux reprend depuis plus de 24 heures en arrière. `MaxReconnects` (5 reconnexions ratées d'affilée par défaut) règle la reconnexion, qui attend une seconde, ou ce que demande le champ `retry` du serveur, avant chaque tentative ; au-delà, le flux lève une `ApiConnectionException`. Le flux d'une boîte de réception se termine une fois cette boîte supprimée ou expirée ; `client.Inboxes.Events.StreamAsync` suit toutes les boîtes que la clé peut lire. Sortir de la boucle, appeler `Close()` ou libérer le flux y met fin sans bruit, et annuler le jeton lève une `OperationCanceledException`.

## Vérifier les webhooks

`Webhook.Verify` contrôle la signature et l'horodatage d'une livraison de [webhook](/docs/fr/concepts/webhooks) avec le secret `whsec_` du endpoint et renvoie l'événement analysé sous forme de `JsonNode`. Passez le corps exactement tel qu'il est arrivé ; les en-têtes peuvent être une fonction de recherche (comme ci-dessous), un dictionnaire ou toute séquence de paires nom et valeur, et les noms sont reconnus quelle que soit la casse :

```csharp
// Program.cs (ASP.NET Core)
var secret = Environment.GetEnvironmentVariable("BILLIONSEND_WEBHOOK_SECRET")!;

app.MapPost("/webhooks/billionsend", async (HttpRequest request) =>
{
    using var reader = new StreamReader(request.Body);
    var body = await reader.ReadToEndAsync();
    try
    {
        var evt = Webhook.Verify(body, name => request.Headers[name], secret);
        Console.WriteLine((string?)evt["type"]);
        return Results.NoContent();
    }
    catch (WebhookVerificationException)
    {
        return Results.BadRequest();
    }
});
```

Une livraison de plus de cinq minutes est refusée (`Tolerance` dans `WebhookVerifyOptions` permet de le changer), et pendant la rotation d'un secret, l'un ou l'autre secret est accepté.
