---
title: SDK para Go
description: Use o BillionSend em Go com o módulo github.com/billionsend/billionsend-go.
ai:
  exclude: true
---

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](/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. Os tipos vêm do documento OpenAPI da API. O código-fonte está em [billionsend/billionsend-go](https://github.com/billionsend/billionsend-go) no GitHub.

## Instalar

Requer Go 1.23 ou mais recente. O módulo usa só a biblioteca padrão.

```sh
go get github.com/billionsend/billionsend-go@v0.1.3
```

## Enviar um e-mail

```go
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](/docs/pt-br/api-reference), 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.

```go
_, 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:

```go
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](/docs/pt-br/inboxes) e responda na conversa:

```go
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](/docs/pt-br/concepts/webhooks) com o segredo `whsec_` do endpoint e devolve o evento já interpretado. Passe o corpo exatamente como chegou:

```go
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.
