SDK de Go
Envía emails, trabaja con una bandeja de entrada y verifica webhooks desde Go con el módulo billionsend-go: toda la API, reintentos y claves de idempotencia.
El módulo github.com/billionsend/billionsend-go es el cliente de BillionSend para Go. Cubre todas las operaciones de la referencia de la API: envío, dominios, contactos, envíos masivos, plantillas, webhooks, bandejas de entrada con sus hilos y borradores, eventos de bandeja en tiempo real y registro de agentes. Sus tipos salen del documento OpenAPI de la API. El código fuente está en billionsend/billionsend-go, en GitHub.
Instalar
Requiere Go 1.23 o superior. El módulo usa solo la biblioteca estándar.
go get github.com/billionsend/billionsend-go
Enviar un email
package main
import (
"context"
"fmt"
"log"
"github.com/billionsend/billionsend-go"
)
func main() {
ctx := context.Background()
client := billionsend.NewClient() // lee BILLIONSEND_API_KEY
sent, err := client.Emails.Send(ctx, &billionsend.SendEmailRequest{
From: "Acme <hello@acme.dev>",
To: []string{"success@simulator.amazonses.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_...")) recibe la clave directamente; WithBaseURL, WithTimeout (por intento, 60 s por defecto), WithMaxRetries, WithHTTPClient y WithHeader definen el resto. BILLIONSEND_BASE_URL sustituye la URL de la API.
Nombres de los métodos
Cada operación es un método con el nombre de su id en la referencia de la API, con cada segmento separado por puntos en mayúsculas al estilo de Go: emails.send es client.Emails.Send y emails.receiving.attachments.list es client.Emails.Receiving.Attachments.List. emails.metrics es client.Emails.Metrics.Get, junto a Links, Countries y Clients.
Un método recibe el contexto, los parámetros de ruta en orden, el cuerpo de la petición (*XxxRequest), los parámetros de consulta y de cabecera (*XxxParams) y, por último, las opciones. Los campos opcionales son punteros, que se crean con billionsend.String, Int64, Float64 y Bool; un campo que admite más de una forma, como una dirección o una lista de ellas, es de tipo any.
Idempotencia y reintentos
Las ocho operaciones de envío (Emails.Send, Emails.Batch, respuestas y reenvíos de correo recibido, Inboxes.Send, Inboxes.Drafts.Send, respuestas y reenvíos de hilos) siempre mandan un Idempotency-Key. Sin WithIdempotencyKey, cada llamada se inventa una que sus reintentos reutilizan, así que reintentar tras un timeout nunca envía dos veces. Una clave tuya también hace segura la repetición desde otro proceso.
Los fallos que merecen otro intento se reintentan dos veces por defecto: 429, 5xx, timeouts, errores de red y el 409 concurrent_idempotent_requests que se devuelve mientras el primer intento con la misma clave sigue en curso. Solo se reintentan las peticiones que se pueden repetir sin riesgo: GET, PUT, DELETE y las operaciones de envío. El cliente espera lo que pida Retry-After, hasta un minuto; si no, aumenta la espera de forma exponencial, de 500 ms a 8 s. WithRequestTimeout, WithRequestMaxRetries, WithRequestHeader y WithResponseHeaders actúan en cada llamada.
Errores
Una llamada fallida devuelve *ValidationError (400, 422), *AuthenticationError (401, o no hay clave configurada), *PermissionDeniedError (403), *NotFoundError (404), *ConflictError (409), *RateLimitError (429, con RetryAfter), *APIError (5xx), *APIConnectionError (sin respuesta) o *APITimeoutError (el intento agotó el tiempo). Cada uno se desenvuelve en *billionsend.Error, con StatusCode, Name (el nombre del error de la API), Message y RequestID, el x-request-id de la respuesta, que es el id de la petición en la página Registros del panel.
_, 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
Los métodos de lista devuelven una página. Cada lista con cursor tiene además un iterador ...All que va pidiendo las páginas siguientes, hacia atrás si se define Before:
for contact, err := range client.Contacts.ListAll(ctx, &billionsend.ContactsListParams{Limit: billionsend.Int64(100)}) {
if err != nil {
return err
}
fmt.Println(contact.Email)
}
La bandeja de entrada de un agente
Espera email nuevo en el flujo de eventos y responde en su hilo:
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 // se agotó la reconexión, o la clave dejó de funcionar
}
ev, ok := item.(*billionsend.InboxStreamEvent)
if !ok {
continue // un *StreamGapEvent: puede faltar algún evento, vuelve a leer los hilos
}
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
}
}
El flujo se reconecta con Last-Event-ID cuando se corta la conexión y reenvía lo que se perdió. Guarda stream.LastEventID() y pásalo de nuevo con WithLastEventID para retomarlo tras un reinicio. Un *StreamGapEvent llega una sola vez, cuando el flujo se retoma desde hace más de 24 horas. WithMaxReconnects (5 por defecto), WithReconnectDelay y WithoutReconnect ajustan la reconexión. El flujo de una bandeja termina cuando esa bandeja se elimina o caduca; client.Inboxes.Events.Stream sigue todas las bandejas que la clave puede leer.
Verificar webhooks
VerifyWebhook comprueba la firma y la marca de tiempo de una entrega de webhook con el secreto whsec_ del endpoint y devuelve el evento ya interpretado. Pasa el cuerpo exactamente como llegó:
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)
})
Una entrega de más de cinco minutos se rechaza y, durante la rotación de un secreto, sirve cualquiera de los dos.
Registro de agentes
signup, err := billionsend.NewClient().Agent.Signup(ctx, &billionsend.AgentSignupRequest{
HumanEmail: "owner@acme.dev",
Name: "Support agent",
})
if err != nil {
return err
}
fmt.Println(signup.Inbox.EmailAddress)
La llamada no necesita clave de API; la respuesta trae la clave nueva y la bandeja de entrada. Consulta Registro de agentes para saber qué puede hacer una cuenta sin reclamar.