---
title: Go SDK
description: 用 billionsend-go 模組在 Go 中傳送郵件、操作收件匣、驗證 Webhook，涵蓋全部 API 操作，內建重試與冪等鍵。
ai:
  exclude: true
---

`github.com/billionsend/billionsend-go` 模組是 BillionSend 面向 Go 的用戶端。它涵蓋 [API 參考](/docs/zh-hant/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-hant/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` 並列。

方法依序接受 context、路徑參數、請求本文（`*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 毫秒到 8 秒採指數退避。`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-hant/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-hant/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-hant/agent-signup)。
