SDK de Java
Envía emails, trabaja con una bandeja de entrada y verifica webhooks desde Java con billionsend-java: toda la API, reintentos y claves de idempotencia.
El paquete com.billionsend:billionsend-java es el cliente de BillionSend para Java. Cubre todas las operaciones de la referencia de la API: envío, dominios, contactos, envíos masivos, plantillas, webhooks, bandejas de entrada con sus hilos y borradores, eventos de bandeja en tiempo real y registro de agentes. Sus métodos se generan a partir del documento OpenAPI de la API. El código fuente está en billionsend/billionsend-java, en GitHub.
Instalar
Requiere Java 17 o superior. Las peticiones pasan por el java.net.http.HttpClient del JDK, y la única dependencia de ejecución es jackson-databind. Con Maven:
<dependency>
<groupId>com.billionsend</groupId>
<artifactId>billionsend-java</artifactId>
<version>0.1.2</version>
</dependency>
Con Gradle:
implementation("com.billionsend:billionsend-java:0.1.2")
Enviar un email
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(); // lee 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_...") recibe la clave directamente. BillionSend.builder() define el resto: apiKey, baseUrl, timeout (por intento, 60 s por defecto), maxRetries, header y httpClient (tu propio java.net.http.HttpClient). BILLIONSEND_BASE_URL sustituye la URL de la API. Un cliente es seguro entre hilos de ejecución: crea uno y compártelo.
Nombres de los métodos
Cada operación es un método con el nombre de su id en la referencia de la API, y cada segmento separado por puntos es un accesor en camelCase: emails.send es client.emails().send(...) y emails.receiving.attachments.list es client.emails().receiving().attachments().list(emailId). emails.metrics es client.emails().metrics().get(), junto a links(), countries() y clients().
Un método recibe los parámetros de ruta en orden, el cuerpo de la petición, los parámetros de consulta y, por último, un RequestOptions; las sobrecargas más cortas omiten lo opcional. Un cuerpo es cualquier cosa que Jackson sepa escribir: un Map, un JsonNode o una clase tuya. La consulta es un Map<String, ?> cuyos valores null se omiten y cuyas listas se separan por comas. Cada respuesta es un JsonNode de Jackson con los nombres de campo propios de la API, así que la referencia de la API la describe campo por campo.
Idempotencia y reintentos
Las ocho operaciones de envío (emails().send, emails().batch, respuestas y reenvíos de correo recibido, inboxes().send, inboxes().drafts().send, respuestas y reenvíos de hilos) siempre mandan un Idempotency-Key. Sin idempotencyKey, cada llamada se inventa una que sus reintentos reutilizan, así que reintentar tras un timeout nunca envía dos veces. Una clave tuya también hace segura la repetición desde otro proceso.
Los fallos que merecen otro intento se reintentan dos veces por defecto: 429, 5xx, timeouts, errores de red y el 409 concurrent_idempotent_requests que se devuelve mientras el primer intento con la misma clave sigue en curso. Solo se reintentan las peticiones que se pueden repetir sin riesgo: GET, PUT, DELETE, las operaciones de envío y cualquier petición a la que le des una clave de idempotencia. El cliente espera lo que pida Retry-After, hasta un minuto (si pide más, lanza la excepción de inmediato); si no, aumenta la espera de forma exponencial de 0,5 s a 8 s. El último argumento de cada método es un RequestOptions cuyo builder acepta idempotencyKey, header, timeout, maxRetries y batchValidation para esa llamada.
Errores
Una llamada fallida lanza ValidationException (400, 422), AuthenticationException (401, o no hay clave configurada), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), RateLimitException (429, con getRetryAfter() en segundos), ApiException (5xx), ApiConnectionException (sin respuesta) o ApiTimeoutException (el intento agotó el tiempo). Todas son no comprobadas, están en com.billionsend y extienden BillionSendException, con getStatusCode() (null si no llegó respuesta), getName() (el nombre del error de la API), getMessage() y getRequestId(), el x-request-id de la respuesta, que es el id de la petición en la página Registros del panel.
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
Los métodos de lista devuelven una página. Cada lista con cursor tiene además un listAll (en la búsqueda de hilos, searchAll) que va pidiendo las páginas siguientes a medida que el bucle las necesita, hacia atrás si se define before; .stream() da los mismos elementos como un Stream<JsonNode>:
for (JsonNode contact : client.contacts().listAll(Map.of("limit", 100))) {
System.out.println(contact.get("email").asText());
}
La bandeja de entrada de un agente
Espera email nuevo en el flujo de eventos y responde en su hilo:
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; // puede faltar algún evento: vuelve a leer los hilos
}
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());
}
}
El flujo se reconecta con Last-Event-ID cuando se corta la conexión y reenvía lo que se perdió. Guarda stream.lastEventId() y pásalo de nuevo con EventStreamOptions.builder().lastEventId(...) para retomarlo tras un reinicio. Un StreamGapEvent llega una sola vez, cuando el flujo se retoma desde hace más de 24 horas. maxReconnects (5 por defecto; después, el bucle lanza una ApiConnectionException), reconnectDelay y reconnect(false) ajustan la reconexión. El flujo de una bandeja termina cuando esa bandeja se elimina o caduca; client.inboxes().events().stream() sigue todas las bandejas que la clave puede leer.
Verificar webhooks
WebhookVerifier.verify comprueba la firma y la marca de tiempo de una entrega de webhook con el secreto whsec_ del endpoint y devuelve el evento ya interpretado, o lanza una WebhookVerificationException. Pasa el cuerpo exactamente como llegó, y las cabeceras como un 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();
Una entrega de más de cinco minutos se rechaza y, durante la rotación de un secreto, sirve cualquiera de los dos.
Registro de agentes
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());
La llamada no necesita clave de API; la respuesta trae la clave nueva y la bandeja de entrada. Consulta Registro de agentes para saber qué puede hacer una cuenta sin reclamar.