---
title: SDK para Java
description: Use o BillionSend em Java com o pacote com.billionsend:billionsend-java.
ai:
  exclude: true
---

O pacote `com.billionsend:billionsend-java` é o cliente do BillionSend para Java. Ele cobre todas as operações da [referência da API](/docs/pt-br/api-reference): envio, domínios, contatos, broadcasts, templates, webhooks, caixas de entrada com suas conversas e rascunhos, eventos das caixas de entrada em tempo real e cadastro de agentes. Os métodos são gerados a partir do documento OpenAPI da API. O código-fonte está em [billionsend/billionsend-java](https://github.com/billionsend/billionsend-java) no GitHub.

## Instalar

Requer Java 17 ou mais recente. As requisições passam pelo `java.net.http.HttpClient` do JDK, e a única dependência em tempo de execução é o `jackson-databind`. Com Maven:

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

Com Gradle:

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

## Enviar um 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("ana@example.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_...")` recebe a chave diretamente. `BillionSend.builder()` define o resto: `apiKey`, `baseUrl`, `timeout` (por tentativa, padrão de 60 s), `maxRetries`, `header` e `httpClient` (o seu próprio `java.net.http.HttpClient`). `BILLIONSEND_BASE_URL` substitui a URL da API. Um cliente é seguro entre threads: crie um e compartilhe.

## Nomes dos métodos

Cada operação é um método com o nome do seu id na [referência da API](/docs/pt-br/api-reference), cada segmento com pontos virando um acessor em camelCase: `emails.send` é `client.emails().send(...)`, `emails.receiving.attachments.list` é `client.emails().receiving().attachments().list(emailId)`. `emails.metrics` é `client.emails().metrics().get()`, ao lado de `links()`, `countries()` e `clients()`.

Um método recebe os parâmetros de caminho em ordem, o corpo da requisição, os parâmetros de consulta e por fim um `RequestOptions`; sobrecargas mais curtas deixam de fora o que é opcional. Um corpo é qualquer coisa que o Jackson consiga escrever: um `Map`, um `JsonNode` ou uma classe sua. A consulta é um `Map<String, ?>` cujos valores `null` ficam de fora e cujas listas vão separadas por vírgula. Toda resposta é um `JsonNode` do Jackson com os nomes de campo da própria API, então a referência da API a descreve campo a campo.

## Idempotência e novas tentativas

As oito operações de envio (`emails().send`, `emails().batch`, respostas e encaminhamentos de e-mails recebidos, `inboxes().send`, `inboxes().drafts().send`, respostas e encaminhamentos em conversas) sempre enviam um `Idempotency-Key`. Sem `idempotencyKey`, cada chamada cria uma chave que as suas novas tentativas reutilizam, então uma nova tentativa depois de um timeout nunca envia duas vezes; a sua própria chave também deixa segura uma repetição vinda de outro processo.

Falhas que valem nova tentativa são repetidas duas vezes por padrão: 429, 5xx, timeouts, erros de rede e o `409 concurrent_idempotent_requests` respondido enquanto a primeira tentativa com a mesma chave ainda está em andamento. Só são repetidas as requisições seguras de repetir: `GET`, `PUT`, `DELETE`, as operações de envio e qualquer requisição a que você dê uma chave de idempotência. O cliente espera o que o `Retry-After` pede, até um minuto (uma espera maior lança o erro na hora), e senão recua exponencialmente de 0,5 s até 8 s. O último argumento de todo método é um `RequestOptions` cujo builder aceita `idempotencyKey`, `header`, `timeout`, `maxRetries` e `batchValidation` para aquela chamada.

## Erros

Uma chamada que falha lança `ValidationException` (400, 422), `AuthenticationException` (401, ou nenhuma chave configurada), `PermissionDeniedException` (403), `NotFoundException` (404), `ConflictException` (409), `RateLimitException` (429, com `getRetryAfter()` em segundos), `ApiException` (5xx), `ApiConnectionException` (sem resposta) ou `ApiTimeoutException` (a tentativa estourou o tempo). Todas são não verificadas, ficam em `com.billionsend` e estendem `BillionSendException`, com `getStatusCode()` (`null` quando não veio resposta), `getName()` (o nome do erro na API), `getMessage()` e `getRequestId()`, o `x-request-id` da resposta, que é o id da requisição na página Logs do painel.

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

## Listas

Os métodos de lista devolvem uma página. Toda lista com cursor também tem um `listAll` (na busca de conversas, `searchAll`) que busca as páginas seguintes conforme o laço pede, para trás quando `before` está definido; `.stream()` dá os mesmos itens como um `Stream<JsonNode>`:

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

## A caixa de entrada de um agente

Espere e-mails novos no [fluxo de eventos](/docs/pt-br/inboxes) e responda na conversa:

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

O fluxo se reconecta com `Last-Event-ID` quando a conexão cai e reenvia o que perdeu; guarde `stream.lastEventId()` e passe-o de volta com `EventStreamOptions.builder().lastEventId(...)` para retomar depois de reiniciar. Um `StreamGapEvent` chega uma vez quando o fluxo é retomado de mais de 24 horas atrás. `maxReconnects` (padrão 5, depois do qual o laço lança uma `ApiConnectionException`), `reconnectDelay` e `reconnect(false)` ajustam a reconexão. O fluxo de uma caixa termina depois que essa caixa é excluída ou expira; `client.inboxes().events().stream()` acompanha todas as caixas que a chave pode ler.

## Verificar webhooks

`WebhookVerifier.verify` confere a assinatura e o horário de uma entrega de [webhook](/docs/pt-br/concepts/webhooks) com o segredo `whsec_` do endpoint e devolve o evento já interpretado, ou lança uma `WebhookVerificationException`. Passe o corpo exatamente como chegou e os cabeçalhos como um mapa:

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

Uma entrega com mais de cinco minutos é recusada, e durante a rotação de um segredo qualquer um dos dois verifica.
