---
title: Go SDK
description: 用 billionsend-go 模块在 Go 里发送邮件、使用收件箱、验证 Webhook，覆盖全部 API 操作，内置重试与幂等键。
ai:
  exclude: true
---

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

## 安装

需要 Go 1.23 或更高版本。这个模块只使用标准库。

```sh
go get github.com/billionsend/billionsend-go
```

## 发送邮件

```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 参考](/docs/zh-hans/api-reference)里的 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。

```go
_, err := client.Emails.Get(ctx, id)
var notFound *billionsend.NotFoundError
var apiErr *billionsend.Error
switch {
case errors.As(err, &notFound):
	// 没有这封邮件
case errors.As(err, &apiErr):
	log.Printf("%d %s: %s (request %s)", apiErr.StatusCode, apiErr.Name, apiErr.Message, apiErr.RequestID)
}
```

## 列表

列表方法返回一页。每个游标列表还有一个 `...All` 迭代器，会在迭代过程中获取后续的页；设置了 `Before` 时则向后翻：

```go
for contact, err := range client.Contacts.ListAll(ctx, &billionsend.ContactsListParams{Limit: billionsend.Int64(100)}) {
	if err != nil {
		return err
	}
	fmt.Println(contact.Email)
}
```

## Agent 的收件箱

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

```go
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](/docs/zh-hans/concepts/webhooks) 投递的签名和时间戳，并返回解析后的事件。传入的请求体必须与收到时完全一致：

```go
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 注册

```go
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 注册](/docs/zh-hans/agent-signup)。
