.NET-SDK
E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit dem NuGet-Paket BillionSend: jede API-Operation, Wiederholungen, Idempotenzschlüssel.
Das Paket BillionSend ist der BillionSend-Client für .NET. Es deckt jede Operation der API-Referenz ab: Versand, Domains, Kontakte, Newsletter-Versand, Vorlagen, Webhooks, Postfächer mit ihren Threads und Entwürfen, Live-Ereignisse von Postfächern und die Agent-Registrierung. Der Quellcode liegt auf GitHub unter billionsend/billionsend-dotnet.
Installation
Erfordert .NET 8 oder neuer. Das Paket hat keine Abhängigkeiten außer der .NET-Laufzeit: Es nutzt HttpClient und System.Text.Json.
dotnet add package BillionSend --version 0.1.0
E-Mail senden
using BillionSend;
using var client = new BillionSendClient(); // liest 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_...") nimmt den Schlüssel direkt entgegen, und new BillionSendClient(new BillionSendOptions { ... }) legt den Rest fest: ApiKey, BaseUrl, Timeout (pro Versuch, Standard 60 Sekunden), MaxRetries, HttpClient (ein eigener, zum Beispiel aus IHttpClientFactory, den der Client dann nicht freigibt und dessen BaseAddress ignoriert wird), Headers (mit jeder Anfrage gesendet) und JsonSerializerOptions. BILLIONSEND_BASE_URL überschreibt die API-URL. Ein Client lässt sich gefahrlos über Threads hinweg teilen: Erzeugen Sie ihn einmal und behalten Sie ihn für die Lebensdauer der Anwendung.
Methodennamen
Jede Operation ist eine asynchrone Methode, benannt nach ihrer ID in der API-Referenz: der durch Punkte getrennte Pfad als Kette von Ressourcen in PascalCase, mit dem Suffix Async. emails.send ist client.Emails.SendAsync, emails.receiving.attachments.list ist client.Emails.Receiving.Attachments.ListAsync, und agent.claimEmail ist client.Agent.ClaimEmailAsync. emails.metrics ist client.Emails.Metrics.GetAsync, neben LinksAsync, CountriesAsync und ClientsAsync.
Eine Methode nimmt die Pfadparameter der Reihe nach, den Request-Body, die Query-Parameter als Dictionary<string, object?>, die Optionen für diesen Aufruf und einen CancellationToken. Ein Body ist jedes Objekt, das System.Text.Json schreiben kann: ein anonymes Objekt, ein Dictionary, ein JsonNode oder Ihr eigener Typ, dessen Eigenschaftsnamen in snake_case geschrieben werden (aus ReplyTo wird reply_to). Query-Listen gehen kommagetrennt, Booleans als true und false, und null-Werte werden weggelassen. Antworten sind der geparste JSON-Body als JsonNode? mit den Feldnamen der API (sent?["id"]), die API-Referenz beschreibt sie also Feld für Feld. Mit answer.Deserialize<T>() lesen Sie eine in Ihren eigenen Typ ein.
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"]}");
}
Idempotenz und Wiederholungsversuche
Die acht Versand-Operationen (Emails.SendAsync, Emails.BatchAsync, ReplyAsync und ForwardAsync auf empfangene Mails, Inboxes.SendAsync, Inboxes.Drafts.SendAsync, ReplyAsync und ForwardAsync auf Threads) senden immer einen Idempotency-Key. Ohne IdempotencyKey in ihren IdempotentRequestOptions denkt sich jeder Aufruf einen aus (eine UUID), den seine Wiederholungen weiterverwenden. Ein erneuter Versuch nach einem Timeout sendet also nie doppelt. Ihr eigener Schlüssel macht auch eine Wiederholung aus einem anderen Prozess sicher, und eine Wiederholung mit demselben Schlüssel und demselben Body liefert die erste Antwort.
Fehlschläge, bei denen sich ein neuer Versuch lohnt, werden standardmäßig zweimal wiederholt: 429, 5xx, Timeouts, Netzwerkfehler und das 409 concurrent_idempotent_requests, das antwortet, solange der erste Versuch mit demselben Schlüssel noch läuft. Wiederholt werden nur Anfragen, die sich gefahrlos wiederholen lassen: GET, PUT, DELETE und die Versand-Operationen. Der Client wartet so lange, wie Retry-After es verlangt (Sekunden oder ein HTTP-Datum), und wirft sofort, wenn es mehr als eine Minute verlangt. Sonst weicht er exponentiell von 0,5 s bis 8 s zurück, mit Jitter. MaxRetries und Timeout legen Sie am Client fest, und für einen Aufruf lassen sie sich in dessen Optionen überschreiben (new IdempotentRequestOptions { MaxRetries = 0 }). Ein Ereignis-Stream wird nur bis zu seiner Öffnung zeitlich begrenzt.
Fehler
Ein fehlgeschlagener Aufruf wirft ValidationException (400, 422), AuthenticationException (401 oder kein Schlüssel konfiguriert, dann ist Name auf missing_api_key gesetzt, bevor etwas gesendet wird), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), RateLimitException (429, mit RetryAfter in Sekunden), ApiException (5xx), ApiConnectionException (keine Antwort: DNS-, Verbindungs- oder TLS-Fehler) oder ApiTimeoutException (der Versuch hat das Zeitlimit überschritten, eine Art von ApiConnectionException). Alle liegen im Namespace BillionSend und erweitern BillionSendException, die bei jedem anderen Status als sie selbst geworfen wird, mit StatusCode (null, wenn es keine Antwort gab), Name (dem Fehlernamen der API), Message und RequestId, dem x-request-id der Antwort, der zugleich die ID der Anfrage auf der Logs-Seite des Dashboards ist. Wird der CancellationToken abgebrochen, wirft das eine OperationCanceledException, wie überall in .NET.
try
{
var email = await client.Emails.GetAsync(id);
}
catch (NotFoundException)
{
// keine solche E-Mail
}
catch (BillionSendException error)
{
Console.WriteLine($"{error.StatusCode} {error.Name}: {error.Message} (request {error.RequestId})");
throw;
}
Listen
Listen-Methoden liefern eine Seite. Jede Cursor-Liste hat außerdem eine Methode ListAllAsync (SearchAllAsync für die Thread-Suche), die ein IAsyncEnumerable<JsonNode> liefert und die nächsten Seiten nach und nach abruft, rückwärts, wenn before gesetzt ist:
await foreach (var contact in client.Contacts.ListAllAsync(new Dictionary<string, object?> { ["limit"] = 100 }))
{
Console.WriteLine(contact["email"]);
}
Das Postfach eines Agenten
Warten Sie im Ereignis-Stream auf neue Mails und antworten Sie in ihrem Thread:
const string inboxId = "support@acme.dev"; // eine Postfach-ID oder seine Adresse
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; // Ereignisse können fehlen: Threads erneut lesen
}
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 kehrt zurück, sobald der Stream offen ist, oder wirft den Fehler, der ihn abgelehnt hat, und liefert einen EventStream, den Sie mit await foreach lesen. Ein InboxStreamEvent hat Id, Event (den Namen des Webhook-Ereignisses, etwa inbox.email.received), Data (type, created_at, inbox_id und data der Webhook-Nutzdaten) und Payload, das innere data mit den IDs, die Sie als Nächstes lesen. Der Stream verbindet sich mit Last-Event-ID neu, wenn die Verbindung abbricht, und spielt Verpasstes nach. Behalten Sie stream.LastEventId und übergeben Sie es als LastEventId in new EventStreamOptions { ... } zurück, um nach einem Neustart fortzusetzen. Ein StreamGapEvent kommt einmal, wenn der Stream von weiter als 24 Stunden zurück fortgesetzt wird. MaxReconnects (Standard 5 fehlgeschlagene Wiederverbindungen in Folge) steuert das Wiederverbinden, das vor jedem Versuch eine Sekunde wartet oder so lange, wie das Feld retry des Servers verlangt. Danach wirft der Stream ApiConnectionException. Der Stream eines Postfachs endet, nachdem dieses Postfach gelöscht wurde oder abgelaufen ist. client.Inboxes.Events.StreamAsync folgt jedem Postfach, das der Schlüssel lesen kann. Das Verlassen der Schleife, Close() oder das Freigeben des Streams beendet ihn still, und ein abgebrochener Token wirft OperationCanceledException.
Webhooks verifizieren
Webhook.Verify prüft Signatur und Zeitstempel einer Webhook-Zustellung mit dem whsec_-Secret des Endpunkts und liefert das geparste Ereignis als JsonNode. Übergeben Sie den Body genau so, wie er angekommen ist. Die Header können eine Nachschlagefunktion sein (wie unten), ein Dictionary oder eine beliebige Folge von Name-Wert-Paaren, und Namen passen in jeder Schreibweise:
// 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();
}
});
Eine Zustellung, die älter als fünf Minuten ist, wird abgelehnt (Tolerance in WebhookVerifyOptions ändert das), und während einer Rotation des Secrets verifiziert jedes der beiden Secrets.