SDK para .NET
Use o BillionSend em .NET com o pacote NuGet BillionSend.
O pacote BillionSend é o cliente do BillionSend para .NET. 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. O código-fonte está em 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.
dotnet add package BillionSend --version 0.1.0
Enviar um e-mail
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, 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.
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.
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:
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 e responda na conversa:
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 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:
// 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.