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

El paquete `BillionSend` es el cliente de BillionSend para .NET. Cubre todas las operaciones de la [referencia de la API](/docs/es/api-reference): 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](https://github.com/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`.

```sh
dotnet add package BillionSend --version 0.1.0
```

## Enviar un email

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

```csharp
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.

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

```csharp
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](/docs/es/inboxes) y responde en su hilo:

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

```csharp
// 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.
