Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

SDK Java

Envoyez des e-mails, gérez une boîte de réception, vérifiez des webhooks en Java avec billionsend-java : toute l'API, nouvelles tentatives, idempotence.

Le package com.billionsend:billionsend-java est le client BillionSend pour Java. Il couvre toutes les opérations de la référence de l’API : envoi, domaines, contacts, campagnes, templates, webhooks, boîtes de réception avec leurs fils de discussion et leurs brouillons, événements de boîte de réception en direct et inscription des agents. Ses méthodes sont générées à partir du document OpenAPI de l’API. Le code source est sur GitHub : billionsend/billionsend-java.

Installer

Nécessite Java 17 ou plus récent. Les requêtes passent par le java.net.http.HttpClient du JDK, et la seule dépendance d’exécution est jackson-databind. Avec Maven :

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

Avec Gradle :

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

Envoyer un e-mail

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(); // reads 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_...") prend la clé directement. BillionSend.builder() règle le reste : apiKey, baseUrl, timeout (par tentative, 60 s par défaut), maxRetries, header et httpClient (votre propre java.net.http.HttpClient). BILLIONSEND_BASE_URL remplace l’URL de l’API. Un client est thread-safe : créez-en un seul et partagez-le.

Noms des méthodes

Chaque opération est une méthode qui porte le nom de son identifiant dans la référence de l’API, chaque segment séparé par un point devenant un accesseur en camelCase : emails.send devient client.emails().send(...), emails.receiving.attachments.list devient client.emails().receiving().attachments().list(emailId). emails.metrics devient client.emails().metrics().get(), à côté de links(), countries() et clients().

Une méthode prend, dans l’ordre, les paramètres de chemin, le corps de la requête, les paramètres de requête, puis un RequestOptions ; des surcharges plus courtes omettent ce qui est facultatif. Un corps peut être tout ce que Jackson sait écrire : une Map, un JsonNode ou une classe de votre cru. Les paramètres de requête forment une Map<String, ?> dont les valeurs null sont omises et dont les listes sont séparées par des virgules. Chaque réponse est un JsonNode de Jackson avec les noms de champ de l’API elle-même : la référence de l’API les décrit donc champ par champ.

Idempotence et nouvelles tentatives

Les huit opérations d’envoi (emails().send, emails().batch, réponses et transferts d’e-mails reçus, inboxes().send, inboxes().drafts().send, réponses et transferts dans un fil) envoient toujours un Idempotency-Key. Sans idempotencyKey, chaque appel en génère une que ses nouvelles tentatives réutilisent : une nouvelle tentative après un délai dépassé n’envoie donc jamais deux fois. Votre propre clé rend aussi sûre une répétition venue d’un autre processus.

Les échecs qui méritent une nouvelle tentative sont retentés deux fois par défaut : 429, 5xx, délais dépassés, erreurs réseau, et le 409 concurrent_idempotent_requests renvoyé tant que la première tentative avec la même clé est encore en cours. Seules les requêtes sans danger à répéter sont retentées : GET, PUT, DELETE, les opérations d’envoi et toute requête à laquelle vous donnez une clé d’idempotence. Le client attend ce que demande Retry-After, jusqu’à une minute (une attente plus longue lève l’erreur aussitôt), et sinon espace les tentatives de façon exponentielle, de 0,5 s à 8 s. Le dernier argument de chaque méthode est un RequestOptions dont le builder accepte idempotencyKey, header, timeout, maxRetries et batchValidation pour cet appel.

Erreurs

Un appel qui échoue lève ValidationException (400, 422), AuthenticationException (401, ou aucune clé configurée), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), RateLimitException (429, avec getRetryAfter() en secondes), ApiException (5xx), ApiConnectionException (aucune réponse) ou ApiTimeoutException (la tentative a dépassé son délai). Toutes sont non vérifiées (unchecked), se trouvent dans com.billionsend et étendent BillionSendException, avec getStatusCode() (null quand aucune réponse n’est arrivée), getName() (le nom de l’erreur dans l’API), getMessage() et getRequestId(), le x-request-id de la réponse, qui est l’identifiant de la requête dans la page Journaux du tableau de bord.

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

Listes

Les méthodes de liste renvoient une page. Chaque liste à curseur dispose aussi d’un listAll (recherche de fils : searchAll) qui va chercher les pages suivantes à mesure que la boucle les demande, en remontant lorsque before est défini ; .stream() donne les mêmes éléments sous forme de Stream<JsonNode> :

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

La boîte de réception d’un agent

Attendez les nouveaux e-mails sur le flux d’événements et répondez dans leur fil :

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; // events may be missing: read the threads again
    }
    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());
  }
}

Le flux se reconnecte avec Last-Event-ID lorsque la connexion tombe et rejoue ce qu’il a manqué. Gardez stream.lastEventId() et repassez-le avec EventStreamOptions.builder().lastEventId(...) pour reprendre après un redémarrage. Un StreamGapEvent arrive une seule fois lorsque le flux reprend depuis plus de 24 heures en arrière. maxReconnects (5 par défaut, après quoi la boucle lève une ApiConnectionException), reconnectDelay et reconnect(false) règlent la reconnexion. Le flux d’une boîte de réception se termine une fois cette boîte supprimée ou expirée ; client.inboxes().events().stream() suit toutes les boîtes que la clé peut lire.

Vérifier les webhooks

WebhookVerifier.verify contrôle la signature et l’horodatage d’une livraison de webhook avec le secret whsec_ du endpoint, puis renvoie l’événement analysé, ou lève une WebhookVerificationException. Passez le corps exactement tel qu’il est arrivé, et les en-têtes sous forme de 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();

Une livraison de plus de cinq minutes est refusée, et pendant la rotation d’un secret, l’un ou l’autre secret est accepté.

Inscription d’un 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());

L’appel n’a pas besoin de clé API ; la réponse contient la nouvelle clé et la boîte de réception. Voir Inscription d’un agent pour ce qu’un compte non réclamé peut faire.

Cette page vous a-t-elle été utile ?