SDK para Java
Use o BillionSend em Java com o pacote com.billionsend:billionsend-java.
O pacote com.billionsend:billionsend-java é o cliente do BillionSend para Java. Ele cobre todas as operações da referência da API: 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 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:
<dependency>
<groupId>com.billionsend</groupId>
<artifactId>billionsend-java</artifactId>
<version>0.1.0</version>
</dependency>
Com Gradle:
implementation("com.billionsend:billionsend-java:0.1.2")
Enviar um 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("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, 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.
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>:
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 e responda na conversa:
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 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:
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.