---
title: .NET-SDK
description: "E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit dem NuGet-Paket BillionSend: jede API-Operation, Wiederholungen, Idempotenzschlüssel."
ai:
  exclude: true
---

Das Paket `BillionSend` ist der BillionSend-Client für .NET. Es deckt jede Operation der [API-Referenz](/docs/de/api-reference) 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](https://github.com/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`.

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

## E-Mail senden

```csharp
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](/docs/de/api-reference): 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.

```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"]}");
}
```

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

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

```csharp
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](/docs/de/inboxes) auf neue Mails und antworten Sie in ihrem Thread:

```csharp
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](/docs/de/concepts/webhooks)-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:

```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();
    }
});
```

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.
