Go SDK

github.com/messagebird/bird-sdk-go (package bird) est le SDK Go officiel pour l'API Bird. Cette page couvre l'installation, la configuration, les erreurs, les réessais, la pagination et les webhooks. Pour envoyer des e-mails avec le SDK, commencez par le quickstart e-mail Go.

Installation

Exemple de code

go get github.com/messagebird/bird-sdk-go

Nécessite Go 1.24+. Des exemples exécutables par méthode s'affichent sous chaque symbole sur pkg.go.dev.

Créer un client

bird.NewClient accepte des options fonctionnelles du package option. Seule la clé API est requise. Le préfixe bk_{region}_… de la clé sélectionne l'URL de base :

Exemple de code

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Email.Send(context.Background(), bird.EmailSendParams{
		From:    "onboarding@messagebird.dev",
		To:      []string{"delivered@messagebird.dev"},
		Subject: "Hello from Bird",
		HTML:    "<p>My first Bird email.</p>",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

Chaque méthode de API prend le contexte en premier et renvoie (T, error). Transmettez le contexte de votre requête pour propager l'annulation sous forme de context.Canceled ou context.DeadlineExceeded sans l'encapsuler dans une erreur SDK.

Options

Les options s'appliquent dans l'ordre (la dernière l'emporte). Quatre sont réservées à la construction et renvoient une erreur si elles sont passées à un appel individuel : WithAPIKey, WithBaseURL, WithRegion et WithHTTPClient. Toutes les autres fonctionnent à la construction (valeur par défaut du client) comme par appel (surcharge pour cette requête) :

Exemple de code

client, err := bird.NewClient(
  option.WithAPIKey(os.Getenv("BIRD_API_KEY")),
  option.WithTimeout(10*time.Second), // per-attempt; each retry gets a fresh budget
)

// This send does not retry transient failures.
msg, err := client.Email.Send(ctx, params, option.WithMaxRetries(0))

Option	Portée	Effet
WithAPIKey, WithBaseURL, WithRegion, WithHTTPClient	Construction uniquement	Identifiants, résolution du point d'accès et *http.Client sous-jacent.
WithTimeout, WithMaxRetries	Construction ou par appel	Délai par tentative et budget de réessais pour les erreurs transitoires.
WithIdempotencyKey	Par appel	Fixe la clé d'idempotence pour un appel mutant (une clé est générée automatiquement sinon).
WithHeader	Construction ou par appel	En-têtes de requête supplémentaires. Les en-têtes appartenant à SDK (Authorization, Idempotency-Key, …) prévalent.
WithEmailDefaults, WithWebhookSecret, WithResponseInto	Construction ou par appel	Valeurs d'envoi par défaut du canal, secret de signature du webhook et capture brute des métadonnées de transport.

Architecture

Les types réseau et le client bas niveau sont générés à partir de la spécification OpenAPI de Bird. Le package bird, écrit à la main, fournit la surface de ressources organisée (client.Email, client.Webhooks) et des structs de paramètres avec des types Go tels que []string et time.Time. Ses types de réponse sont des alias des modèles générés, pour rester alignés avec le format réseau. Le cœur gère les réessais, les délais et l'idempotence pour chaque ressource. Consultez les concepts SDK pour le modèle complet.

Erreurs

Chaque erreur serveur est un *bird.APIError portant StatusCode, Type (la catégorie d'erreur générale), Code (le code E##### stable), Message et RequestID pour la corrélation avec le support. Deux variantes portent des données supplémentaires : *bird.RateLimitError (un 429, avec RetryAfter) et *bird.ValidationError (un 422, avec des Details par champ). Les deux se déballent en *APIError, donc un seul errors.As(err, &apiErr) intercepte toute réponse serveur. Branchez avec errors.As :

Exemple de code

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	_, err = client.Email.Send(context.Background(), bird.EmailSendParams{
		From: "onboarding@messagebird.dev", To: []string{"delivered@messagebird.dev"}, Subject: "Hello from Bird", HTML: "<p>My first Bird email.</p>",
	})
	if err != nil {
		var rle *bird.RateLimitError
		var ve *bird.ValidationError
		var ae *bird.APIError
		switch {
		case errors.As(err, &rle):
			fmt.Println("rate limited; retry after", rle.RetryAfter)
		case errors.As(err, &ve):
			for _, d := range ve.Details {
				fmt.Printf("%s: %s\n", d.Param, d.Message)
			}
		case errors.As(err, &ae):
			fmt.Printf("API error %s (status %d, request %s)\n", ae.Code, ae.StatusCode, ae.RequestID)
		default:
			log.Print(err) // transport: *bird.ConnectionError or *bird.TimeoutError
		}
	}
}

Les échecs sans réponse HTTP sont des types distincts : *bird.ConnectionError (DNS, connexion refusée) et *bird.TimeoutError (une tentative unique a dépassé son délai). Une signature de webhook invalide est *bird.WebhookVerificationError.

Réessais sûrs

Les erreurs transitoires, y compris les délais dépassés, les réponses 429 et les réponses 5xx, sont réessayées automatiquement. Le budget par défaut est de deux réessais ; ajustez-le avec WithMaxRetries, ou utilisez zéro pour désactiver les réessais. Pour les appels mutants, le SDK génère une clé d'idempotence par appel logique et la réutilise à chaque tentative. Passez option.WithIdempotencyKey pour définir votre propre clé et sécuriser les réessais au niveau applicatif.

Pagination

Les méthodes de liste renvoient un iter.Seq2[*T, error], un itérateur paresseux range-over-func qui récupère les pages au fur et à mesure de la consommation :

Exemple de code

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	for msg, err := range client.Email.List(context.Background(), bird.EmailListParams{Status: bird.EmailStatusBounced}) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(msg.Id)
	}
	page, err := client.Email.ListPage(context.Background(), bird.EmailListParams{}, "")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(len(page.Data)) // page.NextCursor carries the next starting_after
}

Sortir de la boucle arrête la récupération ; une erreur de récupération est émise une seule fois et termine la séquence. Pour un contrôle manuel du curseur, ListPage renvoie une page et le curseur suivant.

Webhooks

client.Webhooks.Unwrap vérifie une signature Standard Webhooks sur le corps brut de la requête et renvoie un événement typé. Configurez le secret de signature avec option.WithWebhookSecret sur le client ou par appel. Passez à Unwrap les octets exacts que vous avez reçus, car analyser et resérialiser le corps invalide la signature :

Exemple de code

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(
		option.WithAPIKey(os.Getenv("BIRD_API_KEY")),
		option.WithWebhookSecret(os.Getenv("BIRD_WEBHOOK_SECRET")),
	)
	if err != nil {
		log.Fatal(err)
	}
	http.HandleFunc("/webhooks/bird", func(w http.ResponseWriter, r *http.Request) {
		body, _ := io.ReadAll(r.Body)
		event, err := client.Webhooks.Unwrap(body, r.Header)
		if err != nil {
			http.Error(w, "invalid signature", http.StatusBadRequest)
			return
		}
		w.WriteHeader(http.StatusNoContent) // ack fast, then process

		payload, _ := event.AsAny()
		switch p := payload.(type) {
		case bird.EmailDeliveredEvent:
			fmt.Println("delivered:", p.Data.EmailId, p.Data.Recipient)
		case bird.EmailBouncedEvent:
			fmt.Println("bounced:", p.Type)
		}
	})
}

Utilisez event.Type() pour le discriminant, ou AsAny() pour le contenu concret. Un type d'événement futur inconnu renvoie une erreur plutôt que de provoquer un panic, de sorte qu'un SDK plus ancien continue de fonctionner avec un serveur plus récent.

Solution de contournement

Les points d'accès pas encore disponibles sur la surface typée sont accessibles via client.Get / Post / Put / Patch / Delete, avec la même authentification, les mêmes réessais et la même gestion de l'idempotence :

Exemple de code

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	var out struct {
		Data []struct {
			Recipient string `json:"recipient"`
		} `json:"data"`
	}
	if err := client.Get(context.Background(), "/v1/email/suppressions", &out); err != nil {
		log.Fatal(err)
	}
	fmt.Println(len(out.Data))
}

Retrouvez les chemins dans la référence API.

Étapes suivantes

Quickstart e-mail Go : envoyez votre premier message et utilisez Send, Get et List.
Concepts SDK : découvrez le modèle transversal aux SDK pour les erreurs, l'idempotence, la pagination et les webhooks.
Référence API : consultez le contrat HTTP sous-jacent.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptShould I use a Bird SDK or call the API directly?Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first email

Obtenir un guide d'implémentation