SDK de .NET
Envía emails, trabaja con una bandeja de entrada y verifica webhooks desde .NET con el paquete NuGet BillionSend: toda la API, reintentos e idempotencia.
El paquete BillionSend es el cliente de BillionSend para .NET. 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. El código fuente está en billionsend/billionsend-dotnet, en GitHub.
Instalar
Requiere .NET 8 o superior. El paquete no tiene más dependencias que el runtime de .NET: usa HttpClient y System.Text.Json.
dotnet add package BillionSend --version 0.1.0
Enviar un email
using BillionSend;
using var client = new BillionSendClient(); // lee BILLIONSEND_API_KEY
var sent = await client.Emails.SendAsync(
new
{
from = "Acme <hello@acme.dev>",
to = new[] { "success@simulator.amazonses.com" },
subject = "Welcome to Acme",
html = "<p>Glad you are here.</p>",
},
new IdempotentRequestOptions { IdempotencyKey = "welcome/ana" });
Console.WriteLine(sent?["id"]);
new BillionSendClient("bs_...") recibe la clave directamente, y new BillionSendClient(new BillionSendOptions { ... }) define el resto: ApiKey, BaseUrl, Timeout (por intento, 60 segundos por defecto), MaxRetries, HttpClient (uno tuyo, por ejemplo de IHttpClientFactory, que el cliente entonces no libera y cuyo BaseAddress se ignora), Headers (se envían con cada petición) y JsonSerializerOptions. BILLIONSEND_BASE_URL sustituye la URL de la API. Un cliente se puede compartir con seguridad entre hilos: créalo una vez y consérvalo mientras viva la aplicación.
Nombres de los métodos
Cada operación es un método asíncrono con el nombre de su id en la referencia de la API, con la ruta separada por puntos como una cadena de recursos en PascalCase y el sufijo Async: emails.send es client.Emails.SendAsync, emails.receiving.attachments.list es client.Emails.Receiving.Attachments.ListAsync y agent.claimEmail es client.Agent.ClaimEmailAsync. emails.metrics es client.Emails.Metrics.GetAsync, junto a LinksAsync, CountriesAsync y ClientsAsync.
Un método recibe los parámetros de ruta en orden, el cuerpo de la petición, los parámetros de consulta como un Dictionary<string, object?>, las opciones de esa llamada y un CancellationToken. Un cuerpo es cualquier objeto que System.Text.Json pueda escribir: un objeto anónimo, un diccionario, un JsonNode o un tipo tuyo, cuyos nombres de propiedad se escriben en snake_case (ReplyTo pasa a ser reply_to). Las listas de la consulta van separadas por comas, los booleanos como true y false, y los valores null se omiten. Las respuestas son el cuerpo JSON interpretado como un JsonNode? con los nombres de campo propios de la API (sent?["id"]), así que la referencia de la API las describe campo por campo; answer.Deserialize<T>() lee una en un tipo tuyo.
var page = await client.Emails.Receiving.ListAsync(new Dictionary<string, object?>
{
["limit"] = 20,
["unread"] = "true",
});
foreach (var email in page!["data"]!.AsArray())
{
Console.WriteLine($"{email!["from"]}: {email["subject"]}");
}
Idempotencia y reintentos
Las ocho operaciones de envío (Emails.SendAsync, Emails.BatchAsync, ReplyAsync y ForwardAsync de correo recibido, Inboxes.SendAsync, Inboxes.Drafts.SendAsync, ReplyAsync y ForwardAsync de hilos) siempre mandan un Idempotency-Key. Si no pasas IdempotencyKey en su IdempotentRequestOptions, cada llamada se inventa una (un UUID) 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, y repetir la misma clave con el mismo cuerpo devuelve la primera respuesta.
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 y las operaciones de envío. El cliente espera lo que pida Retry-After (segundos o una fecha HTTP) y lanza el error de inmediato si pide más de un minuto; si no, aumenta la espera de forma exponencial de 0,5 s a 8 s, con variación aleatoria. MaxRetries y Timeout se definen en el cliente y se pueden sustituir en una llamada con sus opciones (new IdempotentRequestOptions { MaxRetries = 0 }); un flujo de eventos se cronometra solo hasta que se abre.
Errores
Una llamada fallida lanza ValidationException (400, 422), AuthenticationException (401, o no hay clave configurada, con Name igual a missing_api_key antes de enviar nada), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), RateLimitException (429, con RetryAfter en segundos), ApiException (5xx), ApiConnectionException (sin respuesta: fallo de DNS, de conexión o de TLS) o ApiTimeoutException (el intento agotó el tiempo, un tipo de ApiConnectionException). Todas están en el espacio de nombres BillionSend y extienden BillionSendException, que se lanza tal cual con cualquier otro estado, con StatusCode (null si no hubo respuesta), Name (el nombre del error de la API), Message y RequestId, el x-request-id de la respuesta, que es el id de la petición en la página Registros del panel. Cancelar el CancellationToken lanza OperationCanceledException, como en todo .NET.
try
{
var email = await client.Emails.GetAsync(id);
}
catch (NotFoundException)
{
// no such email
}
catch (BillionSendException error)
{
Console.WriteLine($"{error.StatusCode} {error.Name}: {error.Message} (request {error.RequestId})");
throw;
}
Listas
Los métodos de lista devuelven una página. Cada lista con cursor tiene además un método ListAllAsync (SearchAllAsync en la búsqueda de hilos) que devuelve un IAsyncEnumerable<JsonNode> y va pidiendo las páginas siguientes a medida que lees, hacia atrás si se define before:
await foreach (var contact in client.Contacts.ListAllAsync(new Dictionary<string, object?> { ["limit"] = 100 }))
{
Console.WriteLine(contact["email"]);
}
La bandeja de entrada de un agente
Espera email nuevo en el flujo de eventos y responde en su hilo:
const string inboxId = "support@acme.dev"; // el id de una bandeja o su dirección
await using var events = await client.Inboxes.Events.StreamInboxAsync(
inboxId,
new Dictionary<string, object?> { ["types"] = "inbox.email.received" });
await foreach (var item in events)
{
if (item is StreamGapEvent)
{
continue; // puede faltar algún evento: vuelve a leer los hilos
}
var ids = ((InboxStreamEvent)item).Payload;
var threadId = (string?)ids?["thread_id"];
var emailId = (string?)ids?["email_id"];
if (threadId is null || emailId is null)
{
continue;
}
await client.Inboxes.Threads.Emails.ReplyAsync(
inboxId,
threadId,
emailId,
new { text = "Thanks, we are on it." },
new IdempotentRequestOptions { IdempotencyKey = $"reply/{emailId}" });
}
StreamInboxAsync vuelve cuando el flujo está abierto, o lanza el error que lo rechazó, y entrega un EventStream que se lee con await foreach. Un InboxStreamEvent tiene Id, Event (el nombre del evento de webhook, como inbox.email.received), Data (el type, created_at, inbox_id y data del payload del webhook) y Payload, el data interior con los ids que hay que leer a continuación. 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 como LastEventId en new EventStreamOptions { ... } 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 reconexiones fallidas seguidas por defecto) ajusta la reconexión, que espera un segundo, o lo que pida el campo retry del servidor, antes de cada intento; pasado ese límite, el flujo lanza ApiConnectionException. El flujo de una bandeja termina cuando esa bandeja se elimina o caduca; client.Inboxes.Events.StreamAsync sigue todas las bandejas que la clave puede leer. Salir del bucle, Close() o liberar el flujo lo termina sin errores, y cancelar el token lanza OperationCanceledException.
Verificar webhooks
Webhook.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 como un JsonNode. Pasa el cuerpo exactamente como llegó; las cabeceras pueden ser una función de búsqueda (como abajo), un diccionario o cualquier secuencia de pares de nombre y valor, y los nombres coinciden sin distinguir mayúsculas:
// Program.cs (ASP.NET Core)
var secret = Environment.GetEnvironmentVariable("BILLIONSEND_WEBHOOK_SECRET")!;
app.MapPost("/webhooks/billionsend", async (HttpRequest request) =>
{
using var reader = new StreamReader(request.Body);
var body = await reader.ReadToEndAsync();
try
{
var evt = Webhook.Verify(body, name => request.Headers[name], secret);
Console.WriteLine((string?)evt["type"]);
return Results.NoContent();
}
catch (WebhookVerificationException)
{
return Results.BadRequest();
}
});
Una entrega de más de cinco minutos se rechaza (Tolerance en WebhookVerifyOptions lo cambia) y, durante la rotación de un secreto, sirve cualquiera de los dos.