Go SDK

github.com/messagebird/bird-sdk-go (package bird) is de officiële Go-SDK voor de Bird API. Deze pagina behandelt installatie, configuratie, fouten, retries, paginering en webhooks. Om e-mail te versturen met de SDK, begin je met de Go e-mail-quickstart.

Installeren

Codevoorbeeld

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

Vereist Go 1.24+. Uitvoerbare voorbeelden per methode staan onder elk symbool op pkg.go.dev.

Een client aanmaken

bird.NewClient accepteert functionele opties uit het option-package. Alleen de API-sleutel is vereist. Het bk_{region}_…-prefix van de sleutel bepaalt de basis-URL:

Codevoorbeeld

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

Elke API-methode verwacht de context als eerste parameter en retourneert (T, error). Geef de context van je request door om annulering als context.Canceled of context.DeadlineExceeded te propageren, zonder deze in een SDK-error te wrappen.

Opties

Opties worden in volgorde toegepast (een latere optie wint). Vier zijn alleen voor constructie en geven een fout als je ze aan een enkele aanroep doorgeeft: WithAPIKey, WithBaseURL, WithRegion en WithHTTPClient. Al het andere werkt zowel bij constructie (een clientbrede standaard) als per aanroep (een override voor dat ene request):

Codevoorbeeld

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

Optie	Scope	Wat het doet
WithAPIKey, WithBaseURL, WithRegion, WithHTTPClient	Alleen constructie	Credentials, endpoint-resolutie en de onderliggende *http.Client.
WithTimeout, WithMaxRetries	Constructie of per aanroep	Timeout per poging en het retrybudget voor tijdelijke fouten.
WithIdempotencyKey	Per aanroep	Vergrendel de idempotentiesleutel voor één muterende aanroep (anders wordt er een gegenereerd).
WithHeader	Constructie of per aanroep	Extra request-headers. Door SDK beheerde headers (Authorization, Idempotency-Key, …) winnen.
WithEmailDefaults, WithWebhookSecret, WithResponseInto	Constructie of per aanroep	Kanaal-brede verzendstandaarden, het webhook-ondertekeningsgeheim en ruwe transport-metadata-opvang.

Hoe het is opgebouwd

De wire-types en low-level client worden gegenereerd uit de OpenAPI-specificatie van Bird. Het handgeschreven bird-package biedt het samengestelde resource-oppervlak (client.Email, client.Webhooks) en parameterstructs met Go-types zoals []string en time.Time. De response-types zijn aliassen van de gegenereerde modellen om gelijk te blijven met het wire-formaat. De core beheert retries, timeouts en idempotentie voor elke resource. Zie SDK-concepten voor het volledige model.

Fouten

Elke serverfout is een *bird.APIError met StatusCode, Type (de grove foutcategorie), Code (de stabiele E#####-code), Message en RequestID voor supportcorrelatie. Twee varianten bevatten extra data: *bird.RateLimitError (een 429, met RetryAfter) en *bird.ValidationError (een 422, met per-veld Details). Beide unwrappen naar *APIError, zodat een enkele errors.As(err, &apiErr) elke serverrespons opvangt. Vertakking met errors.As:

Codevoorbeeld

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

Fouten zonder HTTP-respons zijn aparte types: *bird.ConnectionError (DNS, verbinding geweigerd) en *bird.TimeoutError (een enkele poging overschreed de timeout). Een ongeldige webhook-handtekening is *bird.WebhookVerificationError.

Veilige retries

Tijdelijke fouten, waaronder timeouts, 429-responses en 5xx-responses, worden automatisch opnieuw geprobeerd. Het standaardbudget is twee retries; pas het aan met WithMaxRetries, of gebruik nul om retries uit te schakelen. Bij muterende aanroepen genereert de SDK één idempotentiesleutel per logische aanroep en hergebruikt die bij elke poging. Geef option.WithIdempotencyKey door om je eigen sleutel in te stellen en retries op applicatieniveau veilig te maken.

Paginering

Lijstmethoden retourneren een iter.Seq2[*T, error], een lazy range-over-func-iterator die pagina's ophaalt naarmate je ze consumeert:

Codevoorbeeld

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
}

Uit de loop breken stopt het ophalen; een ophaalfout wordt eenmaal opgeleverd en beëindigt de reeks. Voor handmatige cursorcontrole retourneert ListPage één pagina plus de volgende cursor.

Webhooks

client.Webhooks.Unwrap verifieert een Standard Webhooks-handtekening over de ruwe request-body en retourneert een getypeerd event. Configureer het ondertekeningsgeheim met option.WithWebhookSecret op de client of per aanroep. Geef Unwrap de exacte bytes die je hebt ontvangen, want parsen en opnieuw serialiseren breekt de handtekening:

Codevoorbeeld

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

Gebruik een switch op event.Type() voor de discriminant, of AsAny() voor de concrete payload. Een onbekend toekomstig eventtype retourneert een fout in plaats van te panicken, zodat een oudere SDK blijft werken met een nieuwere server.

Escape hatch

Endpoints die nog niet op het getypeerde oppervlak staan, zijn bereikbaar via client.Get / Post / Put / Patch / Delete, met dezelfde auth, retries en idempotentie-afhandeling:

Codevoorbeeld

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

De paden vind je in de API-referentie.

Vervolgstappen

Go e-mail-quickstart: Verstuur je eerste bericht en gebruik Send, Get en List.
SDK-concepten: Leer het cross-SDK-model voor fouten, idempotentie, paginering en webhooks.
API-referentie: Bekijk het onderliggende HTTP-contract.

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Begrijp het conceptShould I use a Bird SDK or call the API directly?Volg het leerpadBuild your first integration ImplementatiegidsSend your first email

Ontvang een implementatieoverzicht