---
title: SDK Java
description: "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."
ai:
  exclude: true
---

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](/docs/fr/api-reference) : 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](https://github.com/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 :

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

Avec Gradle :

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

## Envoyer un e-mail

```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(); // 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](/docs/fr/api-reference), 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.

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

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

```java
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](/docs/fr/inboxes) et répondez dans leur fil :

```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; // 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](/docs/fr/concepts/webhooks) 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 :

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

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

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

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](/docs/fr/agent-signup) pour ce qu'un compte non réclamé peut faire.
