SDK para Go
Use o BillionSend em Go com o módulo github.com/billionsend/billionsend-go.
O módulo github.com/billionsend/billionsend-go é o cliente do BillionSend para Go. 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. Os tipos vêm do documento OpenAPI da API. O código-fonte está em billionsend/billionsend-go no GitHub.
Instalar
Requer Go 1.23 ou mais recente. O módulo usa só a biblioteca padrão.
go get github.com/billionsend/billionsend-go@v0.1.3
Enviar um e-mail
package main
import (
"context"
"fmt"
"log"
"github.com/billionsend/billionsend-go"
)
func main() {
ctx := context.Background()
client := billionsend.NewClient() // reads BILLIONSEND_API_KEY
sent, err := client.Emails.Send(ctx, &billionsend.SendEmailRequest{
From: "Acme <hello@acme.dev>",
To: []string{"ana@example.com"},
Subject: "Welcome to Acme",
HTML: billionsend.String("<p>Glad you are here.</p>"),
}, billionsend.WithIdempotencyKey("welcome/ana"))
if err != nil {
log.Fatal(err)
}
fmt.Println(sent.ID)
}
billionsend.NewClient(billionsend.WithAPIKey("bs_...")) recebe a chave diretamente; WithBaseURL, WithTimeout (por tentativa, padrão de 60 s), WithMaxRetries, WithHTTPClient e WithHeader definem o resto. BILLIONSEND_BASE_URL substitui a URL da API.
Nomes dos métodos
Cada operação é um método com o nome do seu id na referência da API, cada segmento separado por ponto com inicial maiúscula, como manda o Go: emails.send é client.Emails.Send, emails.receiving.attachments.list é client.Emails.Receiving.Attachments.List. emails.metrics é client.Emails.Metrics.Get, ao lado de Links, Countries e Clients.
Um método recebe o contexto, os parâmetros de caminho em ordem, o corpo da requisição (*XxxRequest), os parâmetros de consulta e de cabeçalho (*XxxParams) e por fim as opções. Campos opcionais são ponteiros, criados com billionsend.String, Int64, Float64 e Bool; um campo que aceita mais de um formato, como um endereço ou uma lista deles, tem o tipo any.
Idempotência e novas tentativas
As oito operações de envio (Emails.Send, Emails.Batch, respostas e encaminhamentos de e-mails recebidos, Inboxes.Send, Inboxes.Drafts.Send, respostas e encaminhamentos em conversas) sempre enviam um Idempotency-Key. Sem WithIdempotencyKey, cada chamada cria uma chave 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.
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, até um minuto, e senão recua exponencialmente de 500 ms até 8 s. WithRequestTimeout, WithRequestMaxRetries, WithRequestHeader e WithResponseHeaders valem por chamada.
Erros
Uma chamada que falha devolve *ValidationError (400, 422), *AuthenticationError (401, ou nenhuma chave configurada), *PermissionDeniedError (403), *NotFoundError (404), *ConflictError (409), *RateLimitError (429, com RetryAfter), *APIError (5xx), *APIConnectionError (sem resposta) ou *APITimeoutError (a tentativa estourou o tempo). Cada um se desembrulha em *billionsend.Error, com StatusCode, 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.
_, err := client.Emails.Get(ctx, id)
var notFound *billionsend.NotFoundError
var apiErr *billionsend.Error
switch {
case errors.As(err, ¬Found):
// no such email
case errors.As(err, &apiErr):
log.Printf("%d %s: %s (request %s)", apiErr.StatusCode, apiErr.Name, apiErr.Message, apiErr.RequestID)
}
Listas
Os métodos de lista devolvem uma página. Toda lista com cursor também tem um iterador ...All que busca as páginas seguintes conforme avança, para trás quando Before está definido:
for contact, err := range client.Contacts.ListAll(ctx, &billionsend.ContactsListParams{Limit: billionsend.Int64(100)}) {
if err != nil {
return err
}
fmt.Println(contact.Email)
}
A caixa de entrada de um agente
Espere e-mails novos no fluxo de eventos e responda na conversa:
stream, err := client.Inboxes.Events.StreamInbox(ctx, "support@acme.dev", &billionsend.InboxesEventsStreamInboxParams{
Types: billionsend.String("inbox.email.received"),
})
if err != nil {
return err
}
defer stream.Close()
for item, err := range stream.Events() {
if err != nil {
return err // reconnecting ran out, or the key stopped working
}
ev, ok := item.(*billionsend.InboxStreamEvent)
if !ok {
continue // a *StreamGapEvent: events may be missing, read the threads again
}
d := ev.Data.Data
_, err := client.Inboxes.Threads.Emails.Reply(ctx, ev.Data.InboxID, d.ThreadID, d.EmailID,
&billionsend.InboxReplyRequest{Text: billionsend.String("Thanks, we are on it.")},
billionsend.WithIdempotencyKey("reply/"+d.EmailID),
)
if err != nil {
return err
}
}
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 com WithLastEventID para retomar depois de reiniciar. Um *StreamGapEvent chega uma vez quando o fluxo é retomado de mais de 24 horas atrás. WithMaxReconnects (padrão 5), WithReconnectDelay e WithoutReconnect ajustam a reconexão. O fluxo de uma caixa termina depois que essa caixa é excluída ou expira; client.Inboxes.Events.Stream acompanha todas as caixas que a chave pode ler.
Verificar webhooks
VerifyWebhook confere a assinatura e o horário de uma entrega de webhook com o segredo whsec_ do endpoint e devolve o evento já interpretado. Passe o corpo exatamente como chegou:
http.HandleFunc("/webhooks/billionsend", func(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
event, err := billionsend.VerifyWebhook(body, r.Header, os.Getenv("BILLIONSEND_WEBHOOK_SECRET"))
if err != nil {
http.Error(w, "bad signature", http.StatusBadRequest)
return
}
log.Print(event.Type)
w.WriteHeader(http.StatusNoContent)
})
Uma entrega com mais de cinco minutos é recusada, e durante a rotação de um segredo qualquer um dos dois verifica.