---
title: SDK para .NET
description: Use o BillionSend em .NET com o pacote NuGet BillionSend.
ai:
  exclude: true
---

O pacote `BillionSend` é o cliente do BillionSend para .NET. 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. O código-fonte está em [billionsend/billionsend-dotnet](https://github.com/billionsend/billionsend-dotnet) no GitHub.

## Instalar

Requer .NET 8 ou mais recente. O pacote não tem dependências além do runtime do .NET: usa `HttpClient` e `System.Text.Json`.

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

## Enviar um e-mail

```csharp
using BillionSend;

using var client = new BillionSendClient(); // reads BILLIONSEND_API_KEY

var sent = await client.Emails.SendAsync(
    new
    {
        from = "Acme <hello@acme.dev>",
        to = new[] { "ana@example.com" },
        subject = "Welcome to Acme",
        html = "<p>Glad you are here.</p>",
    },
    new IdempotentRequestOptions { IdempotencyKey = "welcome/ana" });

Console.WriteLine(sent?["id"]);
```

`new BillionSendClient("bs_...")` recebe a chave diretamente, e `new BillionSendClient(new BillionSendOptions { ... })` define o resto: `ApiKey`, `BaseUrl`, `Timeout` (por tentativa, padrão de 60 segundos), `MaxRetries`, `HttpClient` (um seu, vindo do `IHttpClientFactory` por exemplo, que o cliente então não descarta e cujo `BaseAddress` é ignorado), `Headers` (enviados em toda requisição) e `JsonSerializerOptions`. `BILLIONSEND_BASE_URL` substitui a URL da API. Um cliente é seguro para compartilhar entre threads: crie-o uma vez e mantenha-o durante toda a vida da aplicação.

## Nomes dos métodos

Cada operação é um método assíncrono com o nome do seu id na [referência da API](/docs/pt-br/api-reference), o caminho com pontos virando uma cadeia de recursos em PascalCase com o sufixo `Async`: `emails.send` é `client.Emails.SendAsync`, `emails.receiving.attachments.list` é `client.Emails.Receiving.Attachments.ListAsync`, e `agent.claimEmail` é `client.Agent.ClaimEmailAsync`. `emails.metrics` é `client.Emails.Metrics.GetAsync`, ao lado de `LinksAsync`, `CountriesAsync` e `ClientsAsync`.

Um método recebe os parâmetros de caminho em ordem, o corpo da requisição, os parâmetros de consulta como um `Dictionary<string, object?>`, as opções daquela chamada e um `CancellationToken`. Um corpo é qualquer objeto que o `System.Text.Json` consiga escrever: um objeto anônimo, um dicionário, um `JsonNode` ou um tipo seu, cujas propriedades são escritas em snake_case (`ReplyTo` vira `reply_to`). As listas de consulta vão separadas por vírgula, os booleanos como `true` e `false`, e os valores `null` são omitidos. As respostas são o corpo JSON interpretado como um `JsonNode?` com os nomes de campo da própria API (`sent?["id"]`), então a referência da API os descreve campo a campo; `answer.Deserialize<T>()` lê uma resposta para um tipo seu.

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

## Idempotência e novas tentativas

As oito operações de envio (`Emails.SendAsync`, `Emails.BatchAsync`, `ReplyAsync` e `ForwardAsync` de e-mails recebidos, `Inboxes.SendAsync`, `Inboxes.Drafts.SendAsync`, `ReplyAsync` e `ForwardAsync` em conversas) sempre enviam um `Idempotency-Key`. Sem `IdempotencyKey` nas suas `IdempotentRequestOptions`, cada chamada cria uma chave (um UUID) 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, e uma repetição com a mesma chave e o mesmo corpo devolve a primeira resposta.

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` e as operações de envio. O cliente espera o que o `Retry-After` pede (em segundos ou como data HTTP), e lança o erro na hora quando ele pede mais de um minuto; senão recua exponencialmente de 0,5 s até 8 s, com variação aleatória. `MaxRetries` e `Timeout` são definidos no cliente e podem ser trocados numa única chamada, nas opções dela (`new IdempotentRequestOptions { MaxRetries = 0 }`); um fluxo de eventos só tem limite de tempo até abrir.

## Erros

Uma chamada que falha lança `ValidationException` (400, 422), `AuthenticationException` (401, ou nenhuma chave configurada, com `Name` igual a `missing_api_key` antes de qualquer envio), `PermissionDeniedException` (403), `NotFoundException` (404), `ConflictException` (409), `RateLimitException` (429, com `RetryAfter` em segundos), `ApiException` (5xx), `ApiConnectionException` (sem resposta: falha de DNS, de conexão ou de TLS) ou `ApiTimeoutException` (a tentativa estourou o tempo, um tipo de `ApiConnectionException`). Todas ficam no namespace `BillionSend` e estendem `BillionSendException`, lançado ele mesmo para qualquer outro status, com `StatusCode` (`null` quando não houve resposta), `Name` (o nome do erro na API), `Message` e `RequestId`, o `x-request-id` da resposta, que é o id da requisição na página Logs do painel. Cancelar o `CancellationToken` lança `OperationCanceledException`, como em todo o .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

Os métodos de lista devolvem uma página. Toda lista com cursor também tem um método `ListAllAsync` (`SearchAllAsync` na busca de conversas) que devolve um `IAsyncEnumerable<JsonNode>`, buscando as páginas seguintes conforme você lê, para trás quando `before` está definido:

```csharp
await foreach (var contact in client.Contacts.ListAllAsync(new Dictionary<string, object?> { ["limit"] = 100 }))
{
    Console.WriteLine(contact["email"]);
}
```

## A caixa de entrada de um agente

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

```csharp
const string inboxId = "support@acme.dev"; // an inbox id or its address

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; // events may be missing: read the threads again
    }

    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` retorna quando o fluxo está aberto, ou lança o erro que o recusou, e entrega um `EventStream` para ler com `await foreach`. Um `InboxStreamEvent` tem `Id`, `Event` (o nome do evento de webhook, como `inbox.email.received`), `Data` (os campos `type`, `created_at`, `inbox_id` e `data` do payload do webhook) e `Payload`, o `data` interno com os ids para ler em seguida. 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 como `LastEventId` em `new EventStreamOptions { ... }` para retomar depois de reiniciar. Um `StreamGapEvent` chega uma vez quando o fluxo é retomado de mais de 24 horas atrás. `MaxReconnects` (padrão de 5 reconexões que falham em sequência) ajusta a reconexão, que espera um segundo, ou o que o campo `retry` do servidor pedir, antes de cada tentativa; passado esse limite o fluxo lança `ApiConnectionException`. O fluxo de uma caixa termina depois que essa caixa é excluída ou expira; `client.Inboxes.Events.StreamAsync` acompanha todas as caixas que a chave pode ler. Sair do laço, chamar `Close()` ou descartar o fluxo o encerra em silêncio, e cancelar o token lança `OperationCanceledException`.

## Verificar webhooks

`Webhook.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 como um `JsonNode`. Passe o corpo exatamente como chegou; os cabeçalhos podem ser uma função de consulta (como abaixo), um dicionário ou qualquer sequência de pares de nome e valor, e os nomes valem em maiúsculas ou minú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();
    }
});
```

Uma entrega com mais de cinco minutos é recusada (`Tolerance`, em `WebhookVerifyOptions`, muda isso), e durante a rotação de um segredo qualquer um dos dois verifica.
