Concetti SDK
Gli SDK TypeScript, Go, Python e PHP seguono un unico design. Ciascuno ha una base generata con tipi e un client di basso livello prodotto dalla specifica OpenAPI di Bird. Un livello scritto a mano gestisce il ciclo di vita della richiesta ed espone la superficie curata. Questa pagina descrive il comportamento condiviso. Le pagine per linguaggio trattano i dettagli idiomatici.
Idempotenza automatica
Ogni mutazione (POST, PUT, PATCH, DELETE) riceve un header Idempotency-Key generato automaticamente. La chiave viene generata una sola volta per chiamata logica e riutilizzata in ogni tentativo successivo. Questo impedisce che una scrittura ripetuta venga applicata due volte. Se un invio va in timeout dopo che il server lo ha elaborato, il tentativo successivo riceve la risposta memorizzata. Passa una chiave personalizzata (idempotencyKey / option.WithIdempotencyKey / idempotency_key per chiamata) quando l'operazione logica coinvolge più di una chiamata SDK, ad esempio un ciclo di ripetizione applicativo attorno all'SDK. Consulta Idempotenza per il protocollo lato server.
Tentativi sicuri
I tentativi sono attivi per impostazione predefinita (maxRetries: 2 in ogni SDK). Il client riprova in caso di errori transitori, inclusi errori di rete, timeout per tentativo, risposte 429 e risposte 5xx riprovabili. Usa un backoff esponenziale con jitter e rispetta l'header Retry-After del server. Gli errori deterministici (401, 404, 422 e altre risposte 4xx) non vengono mai riprovati. Riutilizzare la chiave di idempotenza rende sicuri i tentativi sulle mutazioni. Il timeout si applica a ogni tentativo (60 secondi per impostazione predefinita), quindi una chiamata con più tentativi può durare di più. PHP usa il timeout imposto dal client HTTP iniettato, perché PSR-18 non prevede un timeout portabile per singola richiesta.
Paginazione
Gli endpoint di elenco usano la paginazione a cursore. Ogni SDK supporta l'iterazione nativa, che recupera le pagine successive automaticamente. Per il controllo manuale del cursore, usa l'accessor a pagina singola. Ogni pagina include data e next_cursor; passa il cursore come starting_after per avanzare.
for await (const message of bird.email.list({ status: "bounced" })) {
console.log(message.id);
}
const page = await bird.email.list({ limit: 50 }); // page.data, page.next_cursorfor message in client.email.list(status="delivered"):
print(message.id)
page = client.email.list(status="delivered") # page.data, page.next_cursor
print(len(page.data), page.next_cursor)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$page = $bird->email->list(['status' => 'delivered'])->fetch();
foreach ($page->data as $message) {
echo $message->getId(), "\n";
}
$next = $page->nextCursor; // pass back as starting_after to fetch the next pageInferenza della regione
Le chiavi Bird API codificano la propria regione: bk_{region}_{token}. Il SDK legge il prefisso e instrada automaticamente verso https://{region}.platform.bird.com. Un'opzione region sovrascrive la regione inferita. Un baseUrl esplicito (option.WithBaseURL / base_url) ha la precedenza su entrambi e supporta lo sviluppo locale o i deployment self-hosted. La costruzione fallisce quando la chiave non corrisponde al formato bk_{region}_ e non è impostata alcuna sovrascrittura.
Opzioni per chiamata e configurazione solo alla costruzione
La configurazione ha due livelli. Le impostazioni di identità e trasporto sono solo alla costruzione: la chiave API, l'URL base o la regione, e il client HTTP o l'implementazione fetch. Le impostazioni del ciclo di vita possono essere definite come valori predefiniti alla costruzione e sovrascritte per chiamata: timeout, maxRetries, la chiave di idempotenza e header aggiuntivi. TypeScript, Python e PHP usano un oggetto opzioni finale; Go usa opzioni variadiche option.With…. Gli header di proprietà di SDK (Authorization, User-Agent, Idempotency-Key) hanno la precedenza sugli header forniti dal chiamante. I valori predefiniti di canale, come un from email predefinito, seguono lo stesso schema.
Verifica dei webhook
Ogni SDK fornisce un unico punto di ingresso per la verifica: webhooks.unwrap(rawBody, headers). Implementa Standard Webhooks con HMAC-SHA256 sul payload grezzo e il signing secret del tuo endpoint. Accetta voci di firma con tag v1, rifiuta i timestamp al di fuori di una finestra di tolleranza di 5 minuti e confronta le firme in tempo costante. Passa i byte grezzi del corpo della richiesta esattamente come ricevuti. Parsare e ri-serializzare il JSON modifica i byte e invalida la firma.
In caso di successo, unwrap restituisce un evento tipizzato discriminato su type, come email.delivered o email.bounced. I tipi di evento sconosciuti vengono comunque verificati e decodificati, quindi gestiscili nel tuo ramo default. Un errore di verifica è un errore distinto (BirdWebhookVerificationError / *WebhookVerificationError / WebhookVerificationError); rispondi con 400. Consulta Webhook per la configurazione dell'endpoint e il catalogo degli eventi.
Passi successivi
- Quickstart: invia la tua prima email nel tuo linguaggio e framework.
- Webhook ed eventi: configura un endpoint ed esplora il catalogo degli eventi dietro unwrap.
- Riferimento API: consulta il contratto HTTP usato da ogni SDK.
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Ottieni un brief di implementazione