Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

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.

Esta página foi útil?