SDK Go
Envoyez des e-mails, gérez une boîte de réception et vérifiez des webhooks en Go avec billionsend-go : toute l'API, nouvelles tentatives et idempotence.
Le module github.com/billionsend/billionsend-go est le client BillionSend pour Go. Il couvre toutes les opérations de la référence de l’API : envoi, domaines, contacts, campagnes, templates, webhooks, boîtes de réception avec leurs conversations et brouillons, événements de boîte de réception en direct et inscription d’agents. Ses types viennent du document OpenAPI de l’API. Le code source est billionsend/billionsend-go sur GitHub.
Installation
Go 1.23 ou plus récent est requis. Le module n’utilise que la bibliothèque standard.
go get github.com/billionsend/billionsend-go
Envoyer un 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{"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_...")) prend directement la clé ; WithBaseURL, WithTimeout (par tentative, 60 s par défaut), WithMaxRetries, WithHTTPClient et WithHeader règlent le reste. BILLIONSEND_BASE_URL remplace l’URL de l’API.
Noms des méthodes
Chaque opération est une méthode nommée d’après son identifiant dans la référence de l’API, chaque segment séparé par un point prenant la majuscule de Go : emails.send devient client.Emails.Send, emails.receiving.attachments.list devient client.Emails.Receiving.Attachments.List. emails.metrics devient client.Emails.Metrics.Get, à côté de Links, Countries et Clients.
Une méthode prend le contexte, les paramètres de chemin dans l’ordre, le corps de la requête (*XxxRequest), les paramètres de requête et d’en-tête (*XxxParams), puis les options. Les champs facultatifs sont des pointeurs, créés avec billionsend.String, Int64, Float64 et Bool ; un champ qui accepte plus d’une forme, comme une adresse ou une liste d’adresses, est typé any.
Idempotence et nouvelles tentatives
Les huit opérations d’envoi (Emails.Send, Emails.Batch, réponses et transferts de courrier reçu, Inboxes.Send, Inboxes.Drafts.Send, réponses et transferts de conversation) envoient toujours une Idempotency-Key. Sans WithIdempotencyKey, chaque appel en fabrique une que ses nouvelles tentatives réutilisent : une nouvelle tentative après un délai dépassé n’envoie donc jamais deux fois ; votre propre clé sécurise aussi une répétition venue d’un autre processus.
Les échecs qui valent une nouvelle tentative sont retentés deux fois par défaut : 429, 5xx, délais dépassés, erreurs réseau, et le 409 concurrent_idempotent_requests répondu tant que la première tentative avec la même clé est encore en cours. Seules les requêtes sans danger à répéter sont retentées : GET, PUT, DELETE et les opérations d’envoi. Le client attend ce que demande Retry-After, jusqu’à une minute, et sinon espace les tentatives de façon exponentielle, de 500 ms à 8 s. WithRequestTimeout, WithRequestMaxRetries, WithRequestHeader et WithResponseHeaders agissent appel par appel.
Erreurs
Un appel en échec renvoie *ValidationError (400, 422), *AuthenticationError (401, ou aucune clé configurée), *PermissionDeniedError (403), *NotFoundError (404), *ConflictError (409), *RateLimitError (429, avec RetryAfter), *APIError (5xx), *APIConnectionError (aucune réponse) ou *APITimeoutError (la tentative a dépassé son délai). Chacune se déballe en *billionsend.Error, avec StatusCode, Name (le nom d’erreur de l’API), Message et RequestID, le x-request-id de la réponse, qui est l’identifiant de la requête sur la page Journaux du tableau de bord.
_, 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)
}
Listes
Les méthodes de liste renvoient une page. Chaque liste à curseur a aussi un itérateur ...All qui récupère les pages suivantes au fur et à mesure, vers l’arrière lorsque Before est défini :
for contact, err := range client.Contacts.ListAll(ctx, &billionsend.ContactsListParams{Limit: billionsend.Int64(100)}) {
if err != nil {
return err
}
fmt.Println(contact.Email)
}
La boîte de réception d’un agent
Attendez le nouveau courrier sur le flux d’événements et répondez dans son fil :
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
}
}
Le flux se reconnecte avec Last-Event-ID lorsque la connexion tombe et rejoue ce qu’il a manqué ; conservez stream.LastEventID() et repassez-le avec WithLastEventID pour reprendre après un redémarrage. Un *StreamGapEvent arrive une seule fois lorsque le flux reprend à plus de 24 heures en arrière. WithMaxReconnects (5 par défaut), WithReconnectDelay et WithoutReconnect règlent la reconnexion. Le flux d’une boîte se termine après la suppression ou l’expiration de cette boîte ; client.Inboxes.Events.Stream suit toutes les boîtes que la clé peut lire.
Vérifier les webhooks
VerifyWebhook vérifie la signature et l’horodatage d’une livraison de webhook avec le secret whsec_ de l’endpoint et renvoie l’événement analysé. Passez le corps exactement tel qu’il est arrivé :
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)
})
Une livraison de plus de cinq minutes est refusée, et pendant une rotation de secret, l’un ou l’autre secret est accepté.
Inscription d’un agent
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)
L’appel n’a pas besoin de clé API ; la réponse contient la nouvelle clé et la boîte de réception. Voir Inscription d’un agent pour ce qu’un compte non réclamé peut faire.