SDK-concepten
De TypeScript-, Go-, Python- en PHP-SDK's volgen één ontwerp. Elke SDK heeft een gegenereerde basis met types en een low-level client die is geproduceerd vanuit de OpenAPI-specificatie van Bird. Een handgeschreven laag beheert de levenscyclus van het verzoek en biedt het samengestelde oppervlak aan. Deze pagina behandelt hun gedeelde gedrag. De taalspecifieke pagina's behandelen idiomatische details.
Auto-idempotentie
Elke mutatie (POST, PUT, PATCH, DELETE) krijgt een automatisch gegenereerde Idempotency-Key-header. De sleutel wordt één keer per logische aanroep gegenereerd en hergebruikt bij elke poging om opnieuw te proberen. Dit voorkomt dat een herhaalde schrijfactie twee keer wordt uitgevoerd. Als een verzending een time-out krijgt nadat de server het verzoek heeft verwerkt, ontvangt de herpoging het opgeslagen antwoord. Geef je eigen sleutel mee (per aanroep idempotencyKey / option.WithIdempotencyKey / idempotency_key) wanneer de logische bewerking meer dan één SDK-aanroep omvat, zoals een retry-loop in de applicatie rond de SDK. Zie Idempotentie voor het server-side protocol.
Veilig opnieuw proberen
Opnieuw proberen is standaard ingeschakeld (maxRetries: 2 in elke SDK). De client probeert tijdelijke fouten opnieuw, waaronder netwerkfouten, time-outs per poging, 429-antwoorden en herstelbare 5xx-antwoorden. Hij gebruikt exponentiële backoff met jitter en respecteert de Retry-After-header van de server. Deterministische fouten (401, 404, 422 en andere 4xx-antwoorden) worden nooit opnieuw geprobeerd. Hergebruik van de idempotentiesleutel maakt het veilig om mutaties opnieuw te proberen. De time-out geldt per poging (standaard 60 seconden), dus een aanroep met herpogingen kan langer duren. PHP gebruikt de time-out die wordt afgedwongen door de geïnjecteerde HTTP-client, omdat PSR-18 geen draagbare time-out per verzoek heeft.
Paginering
Lijstendpoints gebruiken cursorpaginering. Elke SDK ondersteunt native iteratie, die opeenvolgende pagina's automatisch ophaalt. Gebruik voor handmatige cursorbesturing de accessor voor één pagina. Elke pagina bevat data en next_cursor; geef de cursor terug als starting_after om verder te gaan.
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 pageRegio-afleiding
Bird API-sleutels coderen hun regio: bk_{region}_{token}. De SDK leest het prefix en routeert automatisch naar https://{region}.platform.bird.com. Een region-optie overschrijft de afgeleide regio. Een expliciete baseUrl (option.WithBaseURL / base_url) heeft voorrang op beide en ondersteunt lokale ontwikkeling of zelfgehoste implementaties. De constructie mislukt wanneer de sleutel niet overeenkomt met het bk_{region}_-formaat en er geen override is ingesteld.
Opties per aanroep vs. configuratie alleen bij constructie
Configuratie kent twee niveaus. Identiteits- en transportinstellingen zijn alleen bij constructie beschikbaar: de API-sleutel, basis-URL of regio, en de HTTP-client of fetch-implementatie. Levenscyclusinstellingen kun je instellen als standaardwaarden bij constructie en per aanroep overschrijven: timeout, maxRetries, de idempotentiesleutel en extra headers. TypeScript, Python en PHP gebruiken een afsluitend options-object; Go gebruikt variadische option.With…-opties. Headers die eigendom zijn van SDK (Authorization, User-Agent, Idempotency-Key) hebben voorrang op door de aanroeper meegegeven headers. Kanaalstandaarden, zoals een standaard e-mail-from, volgen hetzelfde patroon.
Webhookverificatie
Elke SDK biedt één verificatie-ingangspunt: webhooks.unwrap(rawBody, headers). Het implementeert Standard Webhooks met HMAC-SHA256 over de onbewerkte payload en het ondertekeningsgeheim van je endpoint. Het accepteert v1-getagde handtekeningvermeldingen, wijst timestamps buiten een tolerantievenster van 5 minuten af en vergelijkt handtekeningen in constante tijd. Geef de onbewerkte bytes van de request body exact door zoals ontvangen. Het parsen en opnieuw serialiseren van de JSON wijzigt de bytes en maakt de handtekening ongeldig.
Bij succes retourneert unwrap een getypeerd event dat wordt onderscheiden op type, zoals email.delivered of email.bounced. Onbekende eventtypen worden nog steeds geverifieerd en gedecodeerd, dus verwerk ze in je default-branch. Een mislukte verificatie is een aparte fout (BirdWebhookVerificationError / *WebhookVerificationError / WebhookVerificationError); antwoord met 400. Zie Webhooks voor het instellen van endpoints en de eventcatalogus.
Volgende stappen
- Quickstarts: Verstuur je eerste e-mail in je taal en framework.
- Webhooks en events: Stel een endpoint in en verken de eventcatalogus achter unwrap.
- API-referentie: Bekijk het HTTP-contract dat door elke SDK wordt gebruikt.
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 integrationImplementatiegidsSend your first email
Ontvang een implementatieoverzicht