Conceitos do SDK
Os SDKs de TypeScript, Go, Python e PHP seguem um único design. Cada um tem uma base gerada com tipos e um client de baixo nível produzido a partir da especificação OpenAPI do Bird. Uma camada escrita manualmente gerencia o ciclo de vida da requisição e expõe a superfície curada. Esta página cobre o comportamento compartilhado. As páginas por linguagem cobrem detalhes idiomáticos.
Idempotência automática
Toda mutação (POST, PUT, PATCH, DELETE) recebe um header Idempotency-Key gerado automaticamente. A chave é gerada uma vez por chamada lógica e reutilizada em todas as tentativas de retry. Isso evita que uma escrita reenviada seja aplicada duas vezes. Se um envio expira após o servidor processá-lo, a nova tentativa recebe a resposta armazenada. Passe sua própria chave (idempotencyKey / option.WithIdempotencyKey / idempotency_key por chamada) quando a operação lógica abrange mais de uma chamada ao SDK, como um loop de retry da aplicação em torno do SDK. Consulte Idempotência para o protocolo do lado do servidor.
Retries seguros
Retries estão ativados por padrão (maxRetries: 2 em todo SDK). O client tenta novamente em falhas transitórias, incluindo erros de rede, timeouts por tentativa, respostas 429 e respostas 5xx recuperáveis. Ele usa backoff exponencial com jitter e respeita o header Retry-After do servidor. Falhas determinísticas (401, 404, 422 e outras respostas 4xx) nunca são reenviadas. Reutilizar a chave de idempotência torna os retries de mutação seguros. O timeout se aplica a cada tentativa (60 segundos por padrão), então uma chamada com retries pode demorar mais. O PHP usa o timeout imposto pelo client HTTP injetado, porque o PSR-18 não tem timeout portável por requisição.
Paginação
Endpoints de listagem são paginados por cursor. Todo SDK suporta iteração nativa, que busca páginas sucessivas automaticamente. Para controle manual de cursor, use o acessor de página única. Cada página inclui data e next_cursor; passe o cursor de volta como starting_after para avançar.
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 pageInferência de região
As chaves Bird API codificam sua região: bk_{region}_{token}. O SDK lê o prefixo e roteia para https://{region}.platform.bird.com automaticamente. Uma opção region substitui a região inferida. Um baseUrl explícito (option.WithBaseURL / base_url) tem precedência sobre ambos e suporta desenvolvimento local ou implantações auto-hospedadas. A construção falha quando a chave não corresponde ao formato bk_{region}_ e nenhuma substituição está definida.
Opções por chamada vs configuração somente de construção
A configuração tem dois níveis. Identidade e transporte são somente de construção: a chave API, URL base ou região, e o client HTTP ou a implementação fetch. Configurações de ciclo de vida podem ser definidas como padrões de construção e substituídas por chamada: timeout, maxRetries, a chave de idempotência e headers extras. TypeScript, Python e PHP usam um objeto de opções no final; Go usa opções variádicas option.With…. Headers controlados pelo SDK (Authorization, User-Agent, Idempotency-Key) têm precedência sobre headers fornecidos pelo chamador. Padrões de canal, como um from de e-mail padrão, seguem o mesmo modelo.
Verificação de webhooks
Cada SDK fornece um ponto de entrada de verificação: webhooks.unwrap(rawBody, headers). Ele implementa Standard Webhooks com HMAC-SHA256 sobre o payload bruto e o segredo de assinatura do seu endpoint. Aceita entradas de assinatura marcadas com v1, rejeita timestamps fora de uma janela de tolerância de 5 minutos e compara assinaturas em tempo constante. Passe os bytes brutos do corpo da requisição exatamente como recebidos. Fazer parse e re-serializar o JSON altera os bytes e invalida a assinatura.
Em caso de sucesso, unwrap retorna um evento tipado discriminado por type, como email.delivered ou email.bounced. Tipos de evento desconhecidos ainda são verificados e decodificados, então trate-os no seu branch default. Falha na verificação é um erro distinto (BirdWebhookVerificationError / *WebhookVerificationError / WebhookVerificationError); responda com 400. Consulte Webhooks para configuração de endpoint e o catálogo de eventos.
Próximos passos
- Quickstarts: Envie seu primeiro e-mail na sua linguagem e framework.
- Webhooks e eventos: Configure um endpoint e explore o catálogo de eventos por trás do unwrap.
- Referência do API: Revise o contrato HTTP usado por todo SDK.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Entenda o conceitoShould I use a Bird SDK or call the API directly?Siga o percurso de aprendizagemBuild your first integrationGuia de implementaçãoSend your first email
Obtenha um resumo de implementação