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

`com.billionsend:billionsend-java` 包是 BillionSend 面向 Java 的客户端。它覆盖 [API 参考](/docs/zh-hans/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 s）、`maxRetries`、`header` 和 `httpClient`（你自己的 `java.net.http.HttpClient`）。`BILLIONSEND_BASE_URL` 可以覆盖 API 地址。客户端是线程安全的：创建一个，大家共用。

## 方法命名

每个操作都是一个方法，名字取自它在 [API 参考](/docs/zh-hans/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 s 起按指数退避，最多 8 s。每个方法的最后一个参数是 `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-hans/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-hans/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-hans/agent-signup)。
