---
title: SDK Go
description: "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."
ai:
  exclude: true
---

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](/docs/fr/api-reference) : 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](https://github.com/billionsend/billionsend-go) sur GitHub.

## Installation

Go 1.23 ou plus récent est requis. Le module n'utilise que la bibliothèque standard.

```sh
go get github.com/billionsend/billionsend-go
```

## Envoyer un 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{"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](/docs/fr/api-reference), 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.

```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)
}
```

## 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 :

```go
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](/docs/fr/inboxes) et répondez dans son fil :

```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
	}
}
```

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](/docs/fr/concepts/webhooks) avec le secret `whsec_` de l'endpoint et renvoie l'événement analysé. Passez le corps exactement tel qu'il est arrivé :

```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)
})
```

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

```go
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](/docs/fr/agent-signup) pour ce qu'un compte non réclamé peut faire.
