Go SDK

github.com/messagebird/bird-sdk-go (package bird) adalah SDK Go resmi untuk Bird API SDK. Halaman ini membahas instalasi, konfigurasi, error, retry, paginasi, dan webhook. Untuk mengirim email dengan SDK, mulai dengan Quickstart email Go.

Instal

Contoh kode

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

Membutuhkan Go 1.24+. Contoh per-method yang dapat dijalankan ditampilkan di bawah setiap simbol pada pkg.go.dev.

Membuat client

bird.NewClient menerima functional option dari package option. Hanya key API yang wajib. Prefix bk_{region}_… pada key menentukan base URL:

Contoh kode

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

Setiap method API menerima context sebagai parameter pertama dan mengembalikan (T, error). Teruskan context dari request Anda untuk menyebarkan pembatalan sebagai context.Canceled atau context.DeadlineExceeded tanpa membungkusnya dalam error SDK.

Option

Option diterapkan secara berurutan (option terakhir menang). Empat option bersifat khusus konstruksi dan mengembalikan error jika diteruskan ke satu panggilan: WithAPIKey, WithBaseURL, WithRegion, dan WithHTTPClient. Semua option lainnya berfungsi baik saat konstruksi (default seluruh client) maupun per panggilan (override untuk satu request tersebut):

Contoh kode

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	Cakupan	Fungsi
WithAPIKey, WithBaseURL, WithRegion, WithHTTPClient	Khusus konstruksi	Kredensial, resolusi endpoint, dan *http.Client yang mendasarinya.
WithTimeout, WithMaxRetries	Konstruksi atau per panggilan	Timeout per percobaan dan anggaran retry untuk kegagalan sementara.
WithIdempotencyKey	Per panggilan	Tetapkan idempotency key untuk satu panggilan mutasi (jika tidak, key dibuat otomatis).
WithHeader	Konstruksi atau per panggilan	Header request tambahan. Header milik SDK (Authorization, Idempotency-Key, …) tetap menang.
WithEmailDefaults, WithWebhookSecret, WithResponseInto	Konstruksi atau per panggilan	Default pengiriman seluruh channel, signing secret webhook, dan penangkapan transport-metadata mentah.

Cara pembuatannya

Wire type dan client level rendah dihasilkan dari spesifikasi OpenAPI Bird. Package bird yang ditulis manual menyediakan permukaan resource terkurasi (client.Email, client.Webhooks) dan struct parameter dengan tipe Go seperti []string dan time.Time. Tipe responsnya mengaliaskan model yang dihasilkan agar tetap selaras dengan format wire. Inti SDK mengelola retry, timeout, dan idempotensi untuk setiap resource. Lihat Konsep SDK untuk model lengkap.

Error

Setiap kegagalan server adalah *bird.APIError yang membawa StatusCode, Type (kategori error kasar), Code (kode E##### yang stabil), Message, dan RequestID untuk korelasi dukungan. Dua varian membawa data tambahan: *bird.RateLimitError (429, dengan RetryAfter) dan *bird.ValidationError (422, dengan Details per field). Keduanya di-unwrap ke *APIError, sehingga satu errors.As(err, &apiErr) menangkap setiap respons server. Percabangan dengan errors.As:

Contoh kode

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

Kegagalan tanpa respons HTTP adalah tipe terpisah: *bird.ConnectionError (DNS, koneksi ditolak) dan *bird.TimeoutError (satu percobaan melewati timeout-nya). Tanda tangan webhook yang tidak valid adalah *bird.WebhookVerificationError.

Retry yang aman

Kegagalan sementara, termasuk timeout, respons 429, dan respons 5xx, di-retry secara otomatis. Anggaran default adalah dua retry; atur dengan WithMaxRetries, atau gunakan nol untuk menonaktifkan retry. Untuk panggilan mutasi, SDK menghasilkan satu idempotency key per panggilan logis dan menggunakannya kembali di setiap percobaan. Teruskan option.WithIdempotencyKey untuk menetapkan key Anda sendiri dan membuat retry tingkat aplikasi aman.

Paginasi

Method list mengembalikan iter.Seq2[*T, error], iterator range-over-func yang malas dan mengambil halaman saat Anda mengonsumsinya:

Contoh kode

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
}

Keluar dari loop menghentikan pengambilan; error pengambilan dihasilkan sekali dan mengakhiri urutan. Untuk kontrol kursor manual, ListPage mengembalikan satu halaman beserta kursor berikutnya.

Webhook

client.Webhooks.Unwrap memverifikasi tanda tangan Standard Webhooks atas body request mentah dan mengembalikan event bertipe. Konfigurasikan signing secret dengan option.WithWebhookSecret pada client atau per panggilan. Teruskan ke Unwrap byte persis yang Anda terima karena mem-parse dan men-serialize ulang akan merusak tanda tangan:

Contoh kode

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

Gunakan switch pada event.Type() untuk diskriminan, atau AsAny() untuk payload konkret. Tipe event masa depan yang tidak dikenal mengembalikan error alih-alih panic, sehingga SDK yang lebih lama tetap bekerja terhadap server yang lebih baru.

Jalan pintas

Endpoint yang belum ada di permukaan bertipe dapat dijangkau melalui client.Get / Post / Put / Patch / Delete, dengan autentikasi, retry, dan penanganan idempotensi yang sama:

Contoh kode

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

Temukan path-nya di Referensi API.

Langkah selanjutnya

Quickstart email Go: Kirim pesan pertama Anda dan gunakan Send, Get, dan List.
Konsep SDK: Pelajari model lintas-SDK untuk error, idempotensi, paginasi, dan webhook.
Referensi API: Tinjau kontrak HTTP yang mendasarinya.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Pahami konsepnyaShould I use a Bird SDK or call the API directly?Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first email

Dapatkan ringkasan implementasi