Go SDK

github.com/messagebird/bird-sdk-go (Paket bird) ist das offizielle Go SDK für die Bird API. Diese Seite behandelt Installation, Konfiguration, Fehler, Wiederholungen, Paginierung und Webhooks. Um E-Mails mit dem SDK zu senden, beginnen Sie mit dem Go-E-Mail-Schnellstart.

Installieren

Codebeispiel

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

Erfordert Go 1.24+. Ausführbare Beispiele pro Methode werden unter jedem Symbol auf pkg.go.dev angezeigt.

Client erstellen

bird.NewClient nimmt funktionale Optionen aus dem Paket option entgegen. Nur der API-Schlüssel ist erforderlich. Das Präfix bk_{region}_… des Schlüssels bestimmt die Basis-URL:

Codebeispiel

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

Jede API-Methode erwartet den Context als erstes Argument und gibt (T, error) zurück. Übergeben Sie den Context Ihres Requests, um einen Abbruch als context.Canceled oder context.DeadlineExceeded weiterzugeben, ohne ihn in einen SDK-Fehler zu verpacken.

Optionen

Optionen werden der Reihe nach angewendet (eine spätere Option gewinnt). Vier sind nur bei der Erstellung verwendbar und geben einen Fehler zurück, wenn sie an einen einzelnen Aufruf übergeben werden: WithAPIKey, WithBaseURL, WithRegion und WithHTTPClient. Alles andere funktioniert sowohl bei der Erstellung (clientweiter Standard) als auch pro Aufruf (ein Override für diesen einen Request):

Codebeispiel

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	Geltungsbereich	Beschreibung
WithAPIKey, WithBaseURL, WithRegion, WithHTTPClient	Nur bei Erstellung	Anmeldedaten, Endpoint-Auflösung und der zugrunde liegende *http.Client.
WithTimeout, WithMaxRetries	Erstellung oder pro Aufruf	Timeout pro Versuch und das Wiederholungsbudget für transiente Fehler.
WithIdempotencyKey	Pro Aufruf	Legt den Idempotenzschlüssel für einen mutierenden Aufruf fest (andernfalls wird einer generiert).
WithHeader	Erstellung oder pro Aufruf	Zusätzliche Request-Header. Von SDK verwaltete Header (Authorization, Idempotency-Key, …) haben Vorrang.
WithEmailDefaults, WithWebhookSecret, WithResponseInto	Erstellung oder pro Aufruf	Kanalweite Sendestandards, das Webhook-Signaturgeheimnis und die Erfassung roher Transport-Metadaten.

So ist es aufgebaut

Die Wire-Typen und der Low-Level-Client werden aus der OpenAPI-Spezifikation von Bird generiert. Das handgeschriebene Paket bird stellt die kuratierte Ressourcenoberfläche (client.Email, client.Webhooks) und Parameter-Structs mit Go-Typen wie []string und time.Time bereit. Seine Antworttypen sind Aliase der generierten Modelle, um mit dem Wire-Format übereinzustimmen. Der Kern verwaltet Wiederholungen, Timeouts und Idempotenz für jede Ressource. Siehe SDK-Konzepte für das vollständige Modell.

Fehler

Jeder Serverfehler ist ein *bird.APIError mit StatusCode, Type (die grobe Fehlerkategorie), Code (der stabile E#####-Code), Message und RequestID für die Support-Korrelation. Zwei Varianten tragen zusätzliche Daten: *bird.RateLimitError (ein 429, mit RetryAfter) und *bird.ValidationError (ein 422, mit feldspezifischen Details). Beide lassen sich zu *APIError unwrappen, sodass ein einzelnes errors.As(err, &apiErr) jede Serverantwort abfängt. Verzweigen Sie mit errors.As:

Codebeispiel

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

Fehler ohne HTTP-Antwort sind eigene Typen: *bird.ConnectionError (DNS, Verbindung abgelehnt) und *bird.TimeoutError (ein einzelner Versuch hat sein Timeout überschritten). Eine ungültige Webhook-Signatur ist *bird.WebhookVerificationError.

Sichere Wiederholungen

Transiente Fehler, einschließlich Timeouts, 429-Antworten und 5xx-Antworten, werden automatisch wiederholt. Das Standardbudget beträgt zwei Wiederholungen; passen Sie es mit WithMaxRetries an, oder verwenden Sie null, um Wiederholungen zu deaktivieren. Bei mutierenden Aufrufen generiert der SDK einen Idempotenzschlüssel pro logischem Aufruf und verwendet ihn bei jedem Versuch erneut. Übergeben Sie option.WithIdempotencyKey, um einen eigenen Schlüssel zu setzen und Wiederholungen auf Anwendungsebene sicher zu machen.

Paginierung

List-Methoden geben einen iter.Seq2[*T, error] zurück, einen Lazy-Range-over-func-Iterator, der Seiten bei Bedarf abruft:

Codebeispiel

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
}

Ein Abbruch der Schleife stoppt das Abrufen; ein Abruffehler wird einmal zurückgegeben und beendet die Sequenz. Für manuelle Cursor-Steuerung gibt ListPage eine Seite plus den nächsten Cursor zurück.

Webhooks

client.Webhooks.Unwrap verifiziert eine Standard-Webhooks-Signatur über den rohen Request-Body und gibt ein typisiertes Event zurück. Konfigurieren Sie das Signaturgeheimnis mit option.WithWebhookSecret auf dem Client oder pro Aufruf. Übergeben Sie Unwrap die exakten empfangenen Bytes, da Parsen und erneutes Serialisieren die Signatur ungültig macht:

Codebeispiel

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

Verwenden Sie event.Type() als Diskriminante oder AsAny() für die konkrete Payload in einem Switch. Ein unbekannter zukünftiger Event-Typ gibt einen Fehler zurück, anstatt zu paniken, sodass ein älteres SDK mit einem neueren Server weiterhin funktioniert.

Escape Hatch

Endpunkte, die noch nicht auf der typisierten Oberfläche verfügbar sind, erreichen Sie über client.Get / Post / Put / Patch / Delete, mit derselben Authentifizierung, denselben Wiederholungen und derselben Idempotenzbehandlung:

Codebeispiel

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

Die Pfade finden Sie in der API-Referenz.

Nächste Schritte

Go-E-Mail-Schnellstart: Senden Sie Ihre erste Nachricht und verwenden Sie Send, Get und List.
SDK-Konzepte: Lernen Sie das SDK-übergreifende Modell für Fehler, Idempotenz, Paginierung und Webhooks kennen.
API-Referenz: Sehen Sie sich den zugrunde liegenden HTTP-Vertrag an.

Verwandte Ressourcen