Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

SDK .NET

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.

Le package BillionSend est le client BillionSend pour .NET. Il couvre toutes les opérations de la référence de l’API : 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.

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.

dotnet add package BillionSend --version 0.1.0

Envoyer un e-mail

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, 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.

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.

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 :

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 et répondez dans leur fil :

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 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 :

// 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é.

Cette page vous a-t-elle été utile ?