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

`com.billionsend:billionsend-java` 套件是 BillionSend 面向 Java 的用戶端。它涵蓋 [API 參考](/docs/zh-hant/api-reference)中的全部操作：傳送、網域、聯絡人、群發、範本、Webhook、含會話串與草稿的收件匣、即時的收件匣事件，以及 Agent 註冊。它的方法是由 API 的 OpenAPI 文件產生的。原始碼在 GitHub 上的 [billionsend/billionsend-java](https://github.com/billionsend/billionsend-java)。

## 安裝

需要 Java 17 或更新版本。請求經由 JDK 的 `java.net.http.HttpClient` 送出，唯一的執行階段相依套件是 `jackson-databind`。使用 Maven：

```xml
<dependency>
  <groupId>com.billionsend</groupId>
  <artifactId>billionsend-java</artifactId>
  <version>0.1.2</version>
</dependency>
```

使用 Gradle：

```kotlin
implementation("com.billionsend:billionsend-java:0.1.2")
```

## 傳送郵件

```java
import com.billionsend.BillionSend;
import com.billionsend.RequestOptions;
import com.fasterxml.jackson.databind.JsonNode;
import java.util.List;
import java.util.Map;

public class Welcome {
  public static void main(String[] args) {
    BillionSend client = new BillionSend(); // 讀取 BILLIONSEND_API_KEY

    JsonNode sent =
        client.emails().send(
            Map.of(
                "from", "Acme <hello@acme.dev>",
                "to", List.of("success@simulator.amazonses.com"),
                "subject", "Welcome to Acme",
                "html", "<p>Glad you are here.</p>"),
            RequestOptions.builder().idempotencyKey("welcome/ana").build());

    System.out.println(sent.get("id").asText());
  }
}
```

`new BillionSend("bs_...")` 直接傳入金鑰。`BillionSend.builder()` 設定其餘選項：`apiKey`、`baseUrl`、`timeout`（每次嘗試，預設 60 秒）、`maxRetries`、`header` 和 `httpClient`（你自己的 `java.net.http.HttpClient`）。`BILLIONSEND_BASE_URL` 可以覆寫 API 網址。用戶端是執行緒安全的：建立一個並共用它。

## 方法命名

每個操作都是一個方法，以它在 [API 參考](/docs/zh-hant/api-reference)中的 id 命名，每個以點分隔的片段都是一個以 camelCase 命名的存取方法：`emails.send` 是 `client.emails().send(...)`，`emails.receiving.attachments.list` 是 `client.emails().receiving().attachments().list(emailId)`。`emails.metrics` 是 `client.emails().metrics().get()`，與 `links()`、`countries()` 和 `clients()` 並列。

方法依序接受路徑參數、請求本文、查詢參數，然後是一個 `RequestOptions`；較短的多載會省略選填的部分。請求本文可以是 Jackson 能寫出的任何東西：`Map`、`JsonNode` 或你自己的類別。查詢是一個 `Map<String, ?>`，其中的 `null` 值會被略過，清單則以逗號分隔。每個回應都是一個 Jackson `JsonNode`，使用 API 自己的欄位名稱，所以 API 參考逐欄位地描述了它。

## 冪等與重試

八個傳送操作（`emails().send`、`emails().batch`、收到的郵件的回覆與轉寄、`inboxes().send`、`inboxes().drafts().send`、會話串的回覆與轉寄）一律會帶上 `Idempotency-Key`。沒有 `idempotencyKey` 時，每次呼叫都會自己產生一個，並在重試中沿用，所以逾時後的重試不會重複傳送；你自己的鍵還能讓另一個行程中的重複呼叫也保持安全。

值得重試的失敗預設會重試兩次：429、5xx、逾時、網路錯誤，以及同一個鍵的第一次請求仍在執行時回傳的 `409 concurrent_idempotent_requests`。只有重複執行也安全的請求才會重試：`GET`、`PUT`、`DELETE`、傳送操作，以及任何你給了冪等鍵的請求。用戶端依 `Retry-After` 的要求等待，最長一分鐘（要求等得更久時會立即拋出），其餘情況從 0.5 秒到 8 秒採指數退避。每個方法的最後一個參數都是 `RequestOptions`，它的建構器接受 `idempotencyKey`、`header`、`timeout`、`maxRetries` 和 `batchValidation`，供該次呼叫使用。

## 錯誤

失敗的呼叫會拋出 `ValidationException`（400、422）、`AuthenticationException`（401，或沒有設定金鑰）、`PermissionDeniedException`（403）、`NotFoundException`（404）、`ConflictException`（409）、`RateLimitException`（429，`getRetryAfter()` 以秒為單位）、`ApiException`（5xx）、`ApiConnectionException`（沒有回應）或 `ApiTimeoutException`（這次嘗試逾時）。它們都是非受檢例外，位於 `com.billionsend`，並繼承 `BillionSendException`，帶有 `getStatusCode()`（沒有回應時為 `null`）、`getName()`（API 的錯誤名稱）、`getMessage()` 和 `getRequestId()`；`getRequestId()` 是回應的 `x-request-id`，也就是這個請求在控制台日誌頁面上的 id。

```java
import com.billionsend.BillionSendException;
import com.billionsend.NotFoundException;

try {
  JsonNode email = client.emails().get(id);
} catch (NotFoundException e) {
  // 沒有這封郵件
} catch (BillionSendException e) {
  System.err.printf(
      "%s %s: %s (request %s)%n",
      e.getStatusCode(), e.getName(), e.getMessage(), e.getRequestId());
}
```

## 列表

列表方法回傳一頁。每個游標式列表還有一個 `listAll`（會話串搜尋是 `searchAll`），會在迴圈需要時取得後續的頁面，設定了 `before` 時則向前取得；`.stream()` 以 `Stream<JsonNode>` 提供同樣的項目：

```java
for (JsonNode contact : client.contacts().listAll(Map.of("limit", 100))) {
  System.out.println(contact.get("email").asText());
}
```

## Agent 的收件匣

在[事件串流](/docs/zh-hant/inboxes)上等待新郵件，並在它所在的會話串中回覆：

```java
import com.billionsend.EventStream;
import com.billionsend.InboxStreamItem;
import com.billionsend.StreamGapEvent;

Map<String, ?> query = Map.of("types", "inbox.email.received");
try (EventStream stream = client.inboxes().events().streamInbox("support@acme.dev", query)) {
  for (InboxStreamItem item : stream) {
    if (item instanceof StreamGapEvent) {
      continue; // 事件可能有遺漏：重新讀取會話串
    }
    JsonNode event = item.data();
    String emailId = event.path("data").path("email_id").asText();
    client.inboxes().threads().emails().reply(
        event.path("inbox_id").asText(),
        event.path("data").path("thread_id").asText(),
        emailId,
        Map.of("text", "Thanks, we are on it."),
        RequestOptions.builder().idempotencyKey("reply/" + emailId).build());
  }
}
```

連線中斷時，事件串流會帶著 `Last-Event-ID` 重新連線，並補上錯過的事件；保留 `stream.lastEventId()`，並用 `EventStreamOptions.builder().lastEventId(...)` 傳回去，就能在重新啟動後接續。從 24 小時前的位置恢復時，會收到一次 `StreamGapEvent`。`maxReconnects`（預設 5，用完後迴圈會拋出 `ApiConnectionException`）、`reconnectDelay` 和 `reconnect(false)` 可調整重新連線的行為。單一收件匣的事件串流在該收件匣被刪除或到期後結束；`client.inboxes().events().stream()` 會追蹤金鑰能讀取的所有收件匣。

## 驗證 Webhook

`WebhookVerifier.verify` 用端點的 `whsec_` 金鑰檢查一次 [Webhook](/docs/zh-hant/concepts/webhooks) 投遞的簽章和時間戳記，並回傳解析後的事件，否則拋出 `WebhookVerificationException`。傳入的請求本文必須與收到時完全一致，標頭則以 map 傳入：

```java
import com.billionsend.WebhookVerificationException;
import com.billionsend.WebhookVerifier;
import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;

HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);
server.createContext("/webhooks/billionsend", exchange -> {
  byte[] body = exchange.getRequestBody().readAllBytes();
  String secret = System.getenv("BILLIONSEND_WEBHOOK_SECRET");
  int status = 204;
  try {
    JsonNode event = WebhookVerifier.verify(body, exchange.getRequestHeaders(), secret);
    System.out.println(event.get("type").asText());
  } catch (WebhookVerificationException e) {
    status = 400;
  }
  exchange.sendResponseHeaders(status, -1);
  exchange.close();
});
server.start();
```

超過五分鐘的投遞會被拒絕，金鑰輪替期間，新舊兩個金鑰都能通過驗證。

## Agent 註冊

```java
JsonNode signup =
    new BillionSend()
        .agent()
        .signup(Map.of("human_email", "owner@acme.dev", "name", "Support agent"));

System.out.println(signup.path("inbox").path("email_address").asText());
```

這個呼叫不需要 API 金鑰；回應中帶有新的金鑰和收件匣。未認領的帳號可以做什麼，參閱 [Agent 註冊](/docs/zh-hant/agent-signup)。
