Go SDK
用 billionsend-go 模块在 Go 里发送邮件、使用收件箱、验证 Webhook,覆盖全部 API 操作,内置重试与幂等键。
github.com/billionsend/billionsend-go 模块是 BillionSend 面向 Go 的客户端。它覆盖 API 参考里的全部操作:发送、域名、联系人、群发、模板、Webhook、带会话和草稿的收件箱、实时的收件箱事件,以及 Agent 注册。类型来自 API 的 OpenAPI 文档。源码在 GitHub 上的 billionsend/billionsend-go。
安装
需要 Go 1.23 或更高版本。这个模块只使用标准库。
go get github.com/billionsend/billionsend-go
发送邮件
package main
import (
"context"
"fmt"
"log"
"github.com/billionsend/billionsend-go"
)
func main() {
ctx := context.Background()
client := billionsend.NewClient() // 读取 BILLIONSEND_API_KEY
sent, err := client.Emails.Send(ctx, &billionsend.SendEmailRequest{
From: "Acme <hello@acme.dev>",
To: []string{"success@simulator.amazonses.com"},
Subject: "Welcome to Acme",
HTML: billionsend.String("<p>Glad you are here.</p>"),
}, billionsend.WithIdempotencyKey("welcome/ana"))
if err != nil {
log.Fatal(err)
}
fmt.Println(sent.ID)
}
billionsend.NewClient(billionsend.WithAPIKey("bs_...")) 直接传入密钥;WithBaseURL、WithTimeout(每次尝试,默认 60 秒)、WithMaxRetries、WithHTTPClient 和 WithHeader 设置其余选项。BILLIONSEND_BASE_URL 可以覆盖 API 地址。
方法命名
每个操作都是一个方法,名字取自它在 API 参考里的 id,每个用点分隔的部分都按 Go 的习惯首字母大写:emails.send 是 client.Emails.Send,emails.receiving.attachments.list 是 client.Emails.Receiving.Attachments.List。emails.metrics 是 client.Emails.Metrics.Get,旁边还有 Links、Countries 和 Clients。
一个方法依次接收:上下文、路径参数(按顺序)、请求体(*XxxRequest)、查询和请求头参数(*XxxParams),最后是选项。可选字段是指针,用 billionsend.String、Int64、Float64 和 Bool 创建;可以有多种形态的字段,例如一个地址或一组地址,类型是 any。
幂等与重试
八个发送操作(Emails.Send、Emails.Batch、收到邮件的回复与转发、Inboxes.Send、Inboxes.Drafts.Send、会话的回复与转发)总是会带上 Idempotency-Key。如果没有 WithIdempotencyKey,每次调用会自己生成一个,它的重试沿用这个密钥,所以超时后的重试不会重复发送;你自己的密钥还能让另一个进程里的重复调用也保持安全。
值得重试的失败默认会重试两次:429、5xx、超时、网络错误,以及同一个密钥的第一次请求仍在运行时返回的 409 concurrent_idempotent_requests。只有可以安全重复的请求才会重试:GET、PUT、DELETE 和发送操作。客户端按 Retry-After 的要求等待,最长一分钟,其余情况从 500 ms 起按指数退避,最多 8 s。WithRequestTimeout、WithRequestMaxRetries、WithRequestHeader 和 WithResponseHeaders 按单次调用生效。
错误
失败的调用会返回 *ValidationError(400、422)、*AuthenticationError(401,或没有配置密钥)、*PermissionDeniedError(403)、*NotFoundError(404)、*ConflictError(409)、*RateLimitError(429,带 RetryAfter)、*APIError(5xx)、*APIConnectionError(没有响应)或 *APITimeoutError(这次尝试超时)。每个错误都可以解包为 *billionsend.Error,带有 StatusCode、Name(API 的错误名)、Message 和 RequestID;RequestID 是响应的 x-request-id,也就是这个请求在控制台日志页面上的 id。
_, err := client.Emails.Get(ctx, id)
var notFound *billionsend.NotFoundError
var apiErr *billionsend.Error
switch {
case errors.As(err, ¬Found):
// 没有这封邮件
case errors.As(err, &apiErr):
log.Printf("%d %s: %s (request %s)", apiErr.StatusCode, apiErr.Name, apiErr.Message, apiErr.RequestID)
}
列表
列表方法返回一页。每个游标列表还有一个 ...All 迭代器,会在迭代过程中获取后续的页;设置了 Before 时则向后翻:
for contact, err := range client.Contacts.ListAll(ctx, &billionsend.ContactsListParams{Limit: billionsend.Int64(100)}) {
if err != nil {
return err
}
fmt.Println(contact.Email)
}
Agent 的收件箱
在事件流上等待新邮件,并在它所在的会话里回复:
stream, err := client.Inboxes.Events.StreamInbox(ctx, "support@acme.dev", &billionsend.InboxesEventsStreamInboxParams{
Types: billionsend.String("inbox.email.received"),
})
if err != nil {
return err
}
defer stream.Close()
for item, err := range stream.Events() {
if err != nil {
return err // 重连次数用尽,或密钥已失效
}
ev, ok := item.(*billionsend.InboxStreamEvent)
if !ok {
continue // 这是 *StreamGapEvent:事件可能有缺失,重新读取会话
}
d := ev.Data.Data
_, err := client.Inboxes.Threads.Emails.Reply(ctx, ev.Data.InboxID, d.ThreadID, d.EmailID,
&billionsend.InboxReplyRequest{Text: billionsend.String("Thanks, we are on it.")},
billionsend.WithIdempotencyKey("reply/"+d.EmailID),
)
if err != nil {
return err
}
}
连接断开时,事件流会带着 Last-Event-ID 重新连接,并补上错过的事件;保存 stream.LastEventID(),再用 WithLastEventID 传回去,就能在重启之后继续。从 24 小时之前的位置恢复时,会收到一次 *StreamGapEvent。WithMaxReconnects(默认 5)、WithReconnectDelay 和 WithoutReconnect 用来调整重连行为。单个收件箱的事件流在该收件箱被删除或过期后结束;client.Inboxes.Events.Stream 会跟随这把密钥能读取的所有收件箱。
验证 Webhook
VerifyWebhook 用端点的 whsec_ 密钥检查一次 Webhook 投递的签名和时间戳,并返回解析后的事件。传入的请求体必须与收到时完全一致:
http.HandleFunc("/webhooks/billionsend", func(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
event, err := billionsend.VerifyWebhook(body, r.Header, os.Getenv("BILLIONSEND_WEBHOOK_SECRET"))
if err != nil {
http.Error(w, "bad signature", http.StatusBadRequest)
return
}
log.Print(event.Type)
w.WriteHeader(http.StatusNoContent)
})
超过五分钟的投递会被拒绝,密钥轮换期间,新旧两个密钥都能通过验证。
Agent 注册
signup, err := billionsend.NewClient().Agent.Signup(ctx, &billionsend.AgentSignupRequest{
HumanEmail: "owner@acme.dev",
Name: "Support agent",
})
if err != nil {
return err
}
fmt.Println(signup.Inbox.EmailAddress)
这个调用不需要 API 密钥;响应里带有新的密钥和收件箱。未认领的账号可以做什么,见 Agent 注册。