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

Java SDK

用 billionsend-java 套件在 Java 中傳送郵件、操作收件匣、驗證 Webhook,涵蓋全部 API 操作,內建重試與冪等鍵。

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

安裝

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

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

使用 Gradle:

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

傳送郵件

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 參考中的 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。

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> 提供同樣的項目:

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

Agent 的收件匣

在事件串流上等待新郵件,並在它所在的會話串中回覆:

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 投遞的簽章和時間戳記,並回傳解析後的事件,否則拋出 WebhookVerificationException。傳入的請求本文必須與收到時完全一致,標頭則以 map 傳入:

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 註冊

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 註冊。

这个页面有帮助吗?