---
title: .NET SDK
description: 用 BillionSend NuGet 包在 .NET 里发送邮件、使用收件箱、验证 Webhook，覆盖全部 API 操作，内置重试与幂等键。
ai:
  exclude: true
---

`BillionSend` 包是 BillionSend 面向 .NET 的客户端。它覆盖 [API 参考](/docs/zh-hans/api-reference)里的全部操作：发送、域名、联系人、群发、模板、Webhook、带会话和草稿的收件箱、实时的收件箱事件，以及 Agent 注册。源码在 GitHub 上的 [billionsend/billionsend-dotnet](https://github.com/billionsend/billionsend-dotnet)。

## 安装

需要 .NET 8 或更高版本。除 .NET 运行时之外，这个包没有任何依赖：它使用 `HttpClient` 和 `System.Text.Json`。

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

## 发送邮件

```csharp
using BillionSend;

using var client = new BillionSendClient(); // 读取 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_...")` 直接传入密钥，`new BillionSendClient(new BillionSendOptions { ... })` 设置其余选项：`ApiKey`、`BaseUrl`、`Timeout`（每次尝试，默认 60 秒）、`MaxRetries`、`HttpClient`（你自己的实例，例如来自 `IHttpClientFactory` 的，客户端不会释放它，它的 `BaseAddress` 也会被忽略）、`Headers`（随每个请求发送）和 `JsonSerializerOptions`。`BILLIONSEND_BASE_URL` 可以覆盖 API 地址。一个客户端可以在多个线程间安全共享：创建一次，并在应用的整个生命周期内保留。

## 方法命名

每个操作都是一个异步方法，名字取自它在 [API 参考](/docs/zh-hans/api-reference)里的 id：用点分隔的路径写成一串 PascalCase 的资源，再加上 `Async` 后缀。`emails.send` 是 `client.Emails.SendAsync`，`emails.receiving.attachments.list` 是 `client.Emails.Receiving.Attachments.ListAsync`，`agent.claimEmail` 是 `client.Agent.ClaimEmailAsync`。`emails.metrics` 是 `client.Emails.Metrics.GetAsync`，旁边还有 `LinksAsync`、`CountriesAsync` 和 `ClientsAsync`。

一个方法依次接收：路径参数（按顺序）、请求体、作为 `Dictionary<string, object?>` 的查询参数、这次调用的选项和一个 `CancellationToken`。请求体可以是 `System.Text.Json` 能写出的任何对象：匿名对象、字典、`JsonNode` 或你自己的类型，属性名会写成 snake_case（`ReplyTo` 变成 `reply_to`）。查询参数中的列表用逗号分隔，布尔值写成 `true` 和 `false`，值为 `null` 的会被省略。响应是解析后的 JSON 响应体，类型是 `JsonNode?`，字段名就是 API 自己的字段名（`sent?["id"]`），所以 API 参考里的说明可以逐字段对应；`answer.Deserialize<T>()` 可以把它读成你自己的类型。

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

## 幂等与重试

八个发送操作（`Emails.SendAsync`、`Emails.BatchAsync`、收到邮件的 `ReplyAsync` 与 `ForwardAsync`、`Inboxes.SendAsync`、`Inboxes.Drafts.SendAsync`、会话的 `ReplyAsync` 与 `ForwardAsync`）总是会带上 `Idempotency-Key`。如果它们的 `IdempotentRequestOptions` 里没有 `IdempotencyKey`，每次调用会自己生成一个（UUID），它的重试沿用这个密钥，所以超时后的重试不会重复发送；你自己的密钥还能让另一个进程里的重复调用也保持安全，同一个密钥和相同请求体的重复调用会返回第一次的响应。

值得重试的失败默认会重试两次：429、5xx、超时、网络错误，以及同一个密钥的第一次请求仍在运行时返回的 `409 concurrent_idempotent_requests`。只有可以安全重复的请求才会重试：`GET`、`PUT`、`DELETE` 和发送操作。客户端按 `Retry-After` 的要求等待（秒数或 HTTP 日期），要求等待超过一分钟时直接抛出错误；其余情况从 0.5 s 起按指数退避，最多 8 s，并带有随机抖动。`MaxRetries` 和 `Timeout` 在客户端上设置，也可以在单次调用的选项里覆盖（`new IdempotentRequestOptions { MaxRetries = 0 }`）；事件流只在打开之前计时。

## 错误

失败的调用会抛出 `ValidationException`（400、422）、`AuthenticationException`（401，或没有配置密钥，此时在发出任何请求之前就会抛出，`Name` 为 `missing_api_key`）、`PermissionDeniedException`（403）、`NotFoundException`（404）、`ConflictException`（409）、`RateLimitException`（429，`RetryAfter` 以秒为单位）、`ApiException`（5xx）、`ApiConnectionException`（没有响应：DNS、连接或 TLS 失败）或 `ApiTimeoutException`（这次尝试超时，属于 `ApiConnectionException` 的一种）。它们都在 `BillionSend` 命名空间里，并继承自 `BillionSendException`；其余任何状态码抛出的就是 `BillionSendException` 本身。每个异常都带 `StatusCode`（没有响应时为 `null`）、`Name`（API 的错误名）、`Message` 和 `RequestId`；`RequestId` 是响应的 `x-request-id`，也就是这个请求在控制台日志页面上的 id。取消 `CancellationToken` 会抛出 `OperationCanceledException`，这与 .NET 里的其它地方一样。

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

## 列表

列表方法返回一页。每个游标列表还有一个 `ListAllAsync` 方法（会话搜索是 `SearchAllAsync`），返回 `IAsyncEnumerable<JsonNode>`，会在你读取的过程中获取后续的页；设置了 `before` 时则向后翻：

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

## Agent 的收件箱

在[事件流](/docs/zh-hans/inboxes)上等待新邮件，并在它所在的会话里回复：

```csharp
const string inboxId = "support@acme.dev"; // 收件箱 id 或它的地址

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; // 事件可能有缺失：重新读取会话
    }

    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` 在事件流打开后才返回，或者抛出拒绝它的错误，并给出一个 `EventStream`，用 `await foreach` 读取。`InboxStreamEvent` 有 `Id`、`Event`（Webhook 的事件名，例如 `inbox.email.received`）、`Data`（Webhook 负载里的 `type`、`created_at`、`inbox_id` 和 `data`）以及 `Payload`，也就是内层的 `data`，里面有接下来要读取的 id。连接断开时，事件流会带着 `Last-Event-ID` 重新连接，并补上错过的事件；保存 `stream.LastEventId`，再把它作为 `LastEventId` 放进 `new EventStreamOptions { ... }` 传回去，就能在重启之后继续。从 24 小时之前的位置恢复时，会收到一次 `StreamGapEvent`。`MaxReconnects`（默认连续失败 5 次重连）用来调整重连行为，每次尝试之前会等待一秒，或者服务器的 `retry` 字段要求的时间；超过这个次数后，事件流会抛出 `ApiConnectionException`。单个收件箱的事件流在该收件箱被删除或过期后结束；`client.Inboxes.Events.StreamAsync` 会跟随这把密钥能读取的所有收件箱。退出循环、调用 `Close()` 或释放事件流都会让它安静地结束，而取消令牌会抛出 `OperationCanceledException`。

## 验证 Webhook

`Webhook.Verify` 用端点的 `whsec_` 密钥检查一次 [Webhook](/docs/zh-hans/concepts/webhooks) 投递的签名和时间戳，并以 `JsonNode` 的形式返回解析后的事件。传入的请求体必须与收到时完全一致；请求头可以是一个查找函数（如下所示）、一个字典或任何由名称和值组成的键值对序列，名称不区分大小写：

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

超过五分钟的投递会被拒绝（`WebhookVerifyOptions` 里的 `Tolerance` 可以改变这一点），密钥轮换期间，新旧两个密钥都能通过验证。
