跳到内容
Esc
↑↓导航↵打开⌘J预览
本页内容

.NET SDK

用 BillionSend NuGet 包在 .NET 里发送邮件、使用收件箱、验证 Webhook,覆盖全部 API 操作,内置重试与幂等键。

BillionSend 包是 BillionSend 面向 .NET 的客户端。它覆盖 API 参考里的全部操作:发送、域名、联系人、群发、模板、Webhook、带会话和草稿的收件箱、实时的收件箱事件,以及 Agent 注册。源码在 GitHub 上的 billionsend/billionsend-dotnet。

安装

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

dotnet add package BillionSend --version 0.1.0

发送邮件

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 参考里的 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>() 可以把它读成你自己的类型。

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 里的其它地方一样。

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 时则向后翻:

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

Agent 的收件箱

在事件流上等待新邮件,并在它所在的会话里回复:

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 投递的签名和时间戳,并以 JsonNode 的形式返回解析后的事件。传入的请求体必须与收到时完全一致;请求头可以是一个查找函数(如下所示)、一个字典或任何由名称和值组成的键值对序列,名称不区分大小写:

// 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 可以改变这一点),密钥轮换期间,新旧两个密钥都能通过验证。

这个页面有帮助吗?