Go SDK

github.com/messagebird/bird-sdk-go (pakiet bird) to oficjalne SDK Go dla Bird API. Ta strona opisuje instalację, konfigurację, błędy, ponawianie, paginację i webhooki. Aby wysyłać e-maile za pomocą SDK, zacznij od szybkiego startu z e-mailem w Go.

Instalacja

Przykład kodu

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

Wymaga Go 1.24+. Uruchamialne przykłady dla poszczególnych metod wyświetlają się pod każdym symbolem na pkg.go.dev.

Tworzenie klienta

bird.NewClient przyjmuje opcje funkcyjne z pakietu option. Wymagany jest tylko klucz API. Prefiks bk_{region}_… klucza wybiera bazowy URL:

Przykład kodu

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

Każda metoda API przyjmuje kontekst jako pierwszy argument i zwraca (T, error). Przekaż kontekst żądania, aby propagować anulowanie jako context.Canceled lub context.DeadlineExceeded bez opakowywania go w błąd SDK.

Opcje

Opcje są stosowane w kolejności (późniejsza wygrywa). Cztery działają tylko przy konstrukcji i zwracają błąd, jeśli zostaną przekazane do pojedynczego wywołania: WithAPIKey, WithBaseURL, WithRegion i WithHTTPClient. Wszystkie pozostałe działają zarówno przy konstrukcji (domyślna wartość dla klienta), jak i per wywołanie (nadpisanie dla tego jednego żądania):

Przykład kodu

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

Opcja	Zakres	Co robi
WithAPIKey, WithBaseURL, WithRegion, WithHTTPClient	Tylko przy konstrukcji	Dane uwierzytelniające, rozwiązywanie endpointu i bazowy *http.Client.
WithTimeout, WithMaxRetries	Konstrukcja lub per wywołanie	Timeout per próba i budżet ponowień dla błędów przejściowych.
WithIdempotencyKey	Per wywołanie	Przypnij klucz idempotentności do jednego wywołania mutującego (w przeciwnym razie jest generowany automatycznie).
WithHeader	Konstrukcja lub per wywołanie	Dodatkowe nagłówki żądania. Nagłówki należące do SDK (Authorization, Idempotency-Key, …) mają pierwszeństwo.
WithEmailDefaults, WithWebhookSecret, WithResponseInto	Konstrukcja lub per wywołanie	Domyślne ustawienia wysyłki dla kanału, sekret podpisu webhooka i przechwytywanie surowych metadanych transportu.

Jak to jest zbudowane

Typy przewodowe i niskopoziomowy klient są generowane ze specyfikacji OpenAPI Bird. Ręcznie napisany pakiet bird udostępnia wyselekcjonowaną powierzchnię zasobów (client.Email, client.Webhooks) i struktury parametrów z typami Go, takimi jak []string i time.Time. Typy odpowiedzi są aliasami wygenerowanych modeli, aby zachować zgodność z formatem przewodowym. Rdzeń zarządza ponowieniami, timeoutami i idempotentnością dla każdego zasobu. Zobacz koncepcje SDK, aby poznać pełny model.

Błędy

Każdy błąd serwera to *bird.APIError zawierający StatusCode, Type (ogólna kategoria błędu), Code (stabilny kod E#####), Message i RequestID do korelacji ze wsparciem. Dwa warianty zawierają dodatkowe dane: *bird.RateLimitError (429, z RetryAfter) i *bird.ValidationError (422, z Details per pole). Oba rozpakowują się do *APIError, więc pojedynczy errors.As(err, &apiErr) przechwytuje każdą odpowiedź serwera. Rozgałęziaj za pomocą errors.As:

Przykład kodu

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

Błędy bez odpowiedzi HTTP to osobne typy: *bird.ConnectionError (DNS, odmowa połączenia) i *bird.TimeoutError (pojedyncza próba przekroczyła timeout). Nieprawidłowy podpis webhooka to *bird.WebhookVerificationError.

Bezpieczne ponawianie

Błędy przejściowe, w tym timeouty, odpowiedzi 429 i odpowiedzi 5xx, są ponawiane automatycznie. Domyślny budżet to dwa ponowienia; dostosuj go za pomocą WithMaxRetries lub ustaw zero, aby wyłączyć ponawianie. Dla wywołań mutujących SDK generuje jeden klucz idempotentności na wywołanie logiczne i używa go ponownie w każdej próbie. Przekaż option.WithIdempotencyKey, aby ustawić własny klucz i zapewnić bezpieczeństwo ponowień na poziomie aplikacji.

Paginacja

Metody listujące zwracają iter.Seq2[*T, error], leniwy iterator range-over-func, który pobiera strony w miarę ich konsumowania:

Przykład kodu

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
}

Przerwanie pętli zatrzymuje pobieranie; błąd pobierania jest zwracany raz i kończy sekwencję. Aby ręcznie sterować kursorem, ListPage zwraca jedną stronę plus następny kursor.

Webhooki

client.Webhooks.Unwrap weryfikuje podpis Standard Webhooks na surowym ciele żądania i zwraca typowane zdarzenie. Skonfiguruj sekret podpisu za pomocą option.WithWebhookSecret na kliencie lub per wywołanie. Przekaż do Unwrap dokładne bajty, które otrzymałeś, ponieważ parsowanie i ponowna serializacja naruszają podpis:

Przykład kodu

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

Użyj switch na event.Type() jako dyskryminancie lub na AsAny() dla konkretnego payloadu. Nieznany przyszły typ zdarzenia zwraca błąd zamiast panikować, więc starszy SDK dalej działa z nowszym serwerem.

Wyjście awaryjne

Endpointy, które nie są jeszcze na typowanej powierzchni, są dostępne przez client.Get / Post / Put / Patch / Delete, z tą samą obsługą uwierzytelniania, ponowień i idempotentności:

Przykład kodu

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

Znajdź ścieżki w referencji API.

Następne kroki

Szybki start z e-mailem w Go: Wyślij pierwszą wiadomość i użyj Send, Get i List.
Koncepcje SDK: Poznaj model cross-SDK dla błędów, idempotentności, paginacji i webhooków.
Referencja API: Przejrzyj bazowy kontrakt HTTP.

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Zrozum koncepcjęShould I use a Bird SDK or call the API directly?Podążaj ścieżką naukiBuild your first integration Przewodnik wdrożeniowySend your first email

Uzyskaj brief wdrożeniowy