Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

Java-SDK

E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit dem Paket billionsend-java: jede API-Operation, Wiederholungen und Idempotenzschlüssel.

Das Paket com.billionsend:billionsend-java ist der BillionSend-Client für Java. Es deckt jede Operation der API-Referenz 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.

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:

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

Mit Gradle:

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

E-Mail senden

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, 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.

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>:

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 auf neue Mails und antworten Sie in ihrem Thread:

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-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:

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

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.

War diese Seite hilfreich?