---
title: Java-SDK
description: "E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit dem Paket billionsend-java: jede API-Operation, Wiederholungen und Idempotenzschlüssel."
ai:
  exclude: true
---

Das Paket `com.billionsend:billionsend-java` ist der BillionSend-Client für Java. Es deckt jede Operation der [API-Referenz](/docs/de/api-reference) ab: Versand, Domains, Kontakte, Newsletter-Versand, Vorlagen, Webhooks, Postfächer mit ihren Threads und Entwürfen, Live-Ereignisse von Postfächern und die Agent-Registrierung. Seine Methoden werden aus dem OpenAPI-Dokument der API generiert. Der Quellcode liegt auf GitHub unter [billionsend/billionsend-java](https://github.com/billionsend/billionsend-java).

## Installation

Erfordert Java 17 oder neuer. Anfragen laufen über den `java.net.http.HttpClient` des JDK, und die einzige Laufzeit-Abhängigkeit ist `jackson-databind`. Mit Maven:

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

Mit Gradle:

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

## E-Mail senden

```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(); // liest 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_...")` nimmt den Schlüssel direkt entgegen. `BillionSend.builder()` legt den Rest fest: `apiKey`, `baseUrl`, `timeout` (pro Versuch, Standard 60 s), `maxRetries`, `header` und `httpClient` (Ihr eigener `java.net.http.HttpClient`). `BILLIONSEND_BASE_URL` überschreibt die API-URL. Ein Client ist threadsicher: Erzeugen Sie einen und teilen Sie ihn.

## Methodennamen

Jede Operation ist eine Methode, benannt nach ihrer ID in der [API-Referenz](/docs/de/api-reference), jedes durch Punkte getrennte Segment ein Accessor in camelCase: `emails.send` ist `client.emails().send(...)`, `emails.receiving.attachments.list` ist `client.emails().receiving().attachments().list(emailId)`. `emails.metrics` ist `client.emails().metrics().get()`, neben `links()`, `countries()` und `clients()`.

Eine Methode nimmt die Pfadparameter der Reihe nach, den Request-Body, die Query-Parameter und danach ein `RequestOptions`. Kürzere Überladungen lassen Optionales weg. Ein Body ist alles, was Jackson schreiben kann: eine `Map`, ein `JsonNode` oder eine eigene Klasse. Die Query ist eine `Map<String, ?>`, deren `null`-Werte entfallen und deren Listen kommagetrennt übergeben werden. Jede Antwort ist ein Jackson-`JsonNode` mit den Feldnamen der API, sodass die API-Referenz sie Feld für Feld beschreibt.

## Idempotenz und Wiederholungsversuche

Die acht Versand-Operationen (`emails().send`, `emails().batch`, Antworten und Weiterleitungen auf empfangene Mails, `inboxes().send`, `inboxes().drafts().send`, Thread-Antworten und -Weiterleitungen) senden immer einen `Idempotency-Key`. Ohne `idempotencyKey` denkt sich jeder Aufruf einen aus, den seine Wiederholungen weiterverwenden. Ein erneuter Versuch nach einem Timeout sendet also nie doppelt, und Ihr eigener Schlüssel macht auch eine Wiederholung aus einem anderen Prozess sicher.

Fehlschläge, bei denen sich ein neuer Versuch lohnt, werden standardmäßig zweimal wiederholt: 429, 5xx, Timeouts, Netzwerkfehler und das `409 concurrent_idempotent_requests`, das antwortet, solange der erste Versuch mit demselben Schlüssel noch läuft. Wiederholt werden nur Anfragen, die sich gefahrlos wiederholen lassen: `GET`, `PUT`, `DELETE`, die Versand-Operationen und jede Anfrage, der Sie einen Idempotenzschlüssel mitgeben. Der Client wartet so lange, wie `Retry-After` es verlangt, bis zu einer Minute (eine längere Wartezeit wirft sofort eine Ausnahme), und weicht sonst exponentiell von 0,5 s bis 8 s zurück. Das letzte Argument jeder Methode ist ein `RequestOptions`, dessen Builder `idempotencyKey`, `header`, `timeout`, `maxRetries` und `batchValidation` für diesen Aufruf entgegennimmt.

## Fehler

Ein fehlgeschlagener Aufruf wirft `ValidationException` (400, 422), `AuthenticationException` (401 oder kein Schlüssel konfiguriert), `PermissionDeniedException` (403), `NotFoundException` (404), `ConflictException` (409), `RateLimitException` (429, mit `getRetryAfter()` in Sekunden), `ApiException` (5xx), `ApiConnectionException` (keine Antwort) oder `ApiTimeoutException` (der Versuch hat das Zeitlimit überschritten). Alle sind ungeprüft, liegen in `com.billionsend` und erweitern `BillionSendException`, mit `getStatusCode()` (`null`, wenn keine Antwort kam), `getName()` (dem Fehlernamen der API), `getMessage()` und `getRequestId()`, dem `x-request-id` der Antwort, der zugleich die ID der Anfrage auf der Logs-Seite des Dashboards ist.

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

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

## Listen

Listen-Methoden liefern eine Seite. Jede Cursor-Liste hat außerdem ein `listAll` (Thread-Suche: `searchAll`), das die nächsten Seiten abruft, sobald die Schleife sie anfordert, rückwärts, wenn `before` gesetzt ist. `.stream()` liefert dieselben Einträge als `Stream<JsonNode>`:

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

## Das Postfach eines Agenten

Warten Sie im [Ereignis-Stream](/docs/de/inboxes) auf neue Mails und antworten Sie in ihrem Thread:

```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; // Ereignisse können fehlen: Threads erneut lesen
    }
    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());
  }
}
```

Der Stream verbindet sich mit `Last-Event-ID` neu, wenn die Verbindung abbricht, und spielt Verpasstes nach. Behalten Sie `stream.lastEventId()` und übergeben Sie es mit `EventStreamOptions.builder().lastEventId(...)` zurück, um nach einem Neustart fortzusetzen. Ein `StreamGapEvent` kommt einmal, wenn der Stream von weiter als 24 Stunden zurück fortgesetzt wird. `maxReconnects` (Standard 5, danach wirft die Schleife eine `ApiConnectionException`), `reconnectDelay` und `reconnect(false)` steuern das Wiederverbinden. Der Stream eines Postfachs endet, nachdem dieses Postfach gelöscht wurde oder abgelaufen ist. `client.inboxes().events().stream()` folgt jedem Postfach, das der Schlüssel lesen kann.

## Webhooks verifizieren

`WebhookVerifier.verify` prüft Signatur und Zeitstempel einer [Webhook](/docs/de/concepts/webhooks)-Zustellung mit dem `whsec_`-Secret des Endpunkts und liefert das geparste Ereignis oder wirft eine `WebhookVerificationException`. Übergeben Sie den Body genau so, wie er angekommen ist, und die Header als 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();
```

Eine Zustellung, die älter als fünf Minuten ist, wird abgelehnt, und während einer Rotation des Secrets verifiziert jedes der beiden Secrets.

## Agent-Registrierung

```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());
```

Der Aufruf braucht keinen API-Schlüssel. Die Antwort enthält den neuen Schlüssel und das Postfach. Was ein nicht übernommenes Konto darf, steht unter [Agent-Registrierung](/docs/de/agent-signup).
