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

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, &notFound):
	// 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.

Esta página foi útil?