PHP SDK

messagebird/sdk é o SDK PHP oficial para a API da Bird: uma superfície tipada, escrita manualmente sobre uma camada de transporte gerada. Ele tem como alvo PHP 8.2+ e é síncrono; HTTP passa por qualquer cliente PSR-18 que você já tenha (Guzzle, Symfony HttpClient, …), descoberto automaticamente. Esta página cobre o próprio cliente; para enviar e-mail de ponta a ponta, comece pelo quickstart de e-mail em PHP.

Instalação

composer require messagebird/sdk

O pacote é publicado como messagebird/sdk no Packagist.

Construir um cliente

$bird = new Bird(
    getenv('BIRD_API_KEY') ?: '',
    region: 'eu1',                                          // optional; overrides the region inferred from the key prefix
    maxRetries: 2,                                          // retry budget for transient failures (default 2)
    email: new EmailDefaults(from: 'hello@acme.com'),       // optional channel defaults, such as a default sender
    webhookSecret: getenv('BIRD_WEBHOOK_SECRET') ?: null,   // signing secret for $bird->webhooks->unwrap()
);

Apenas a chave API é obrigatória. A região é inferida a partir do prefixo bk_{region}_ da chave (uma chave bk_eu1_… é roteada para https://eu1.platform.bird.com), então a maioria dos clientes é construída apenas com a chave; consulte inferência de região para as regras. baseUrl sobrescreve a região por completo (local ou auto-hospedado). Valores padrão de canal definidos aqui (por exemplo email: new EmailDefaults(from: "hello@acme.com")) tornam esse campo opcional em cada envio, e webhookSecret é o segredo com o qual $bird->webhooks->unwrap() faz a verificação. Configure um timeout por solicitação no cliente PSR-18 que você passa para Bird. PSR-18 não tem timeout portável, então o transporte é o dono dessa configuração.

Primeira chamada

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    subject: 'Hello from Bird',
    html: '<p>My first Bird email.</p>',
);
echo $message->getId(), ' ', $message->getStatus();

A chamada retorna o resultado API diretamente: aqui, uma mensagem de e-mail com seu em_* id. Para um passo a passo executável, siga o quickstart de PHP.

Design de duas camadas

O SDK combina camadas geradas e mantidas manualmente. Os tipos de transporte em MessageBird\Wire vêm da especificação OpenAPI da Bird via jane-php, mantendo os formatos de solicitação e resposta fiéis ao contrato. A camada escrita manualmente fornece $bird->email->send(...), retentativas, idempotência, paginação, erros e verificação de webhooks. Campos de transporte passam literalmente em snake_case, como category e created_at. Apenas identificadores definidos por SDK, incluindo nomes de métodos e opções como idempotencyKey, usam camelCase. Os SDKs de TypeScript, Go e Python compartilham essa arquitetura; consulte conceitos do SDK.

Idempotência e retentativas automáticas

Cada mutação (POST, PUT, PATCH, DELETE) recebe um cabeçalho Idempotency-Key gerado automaticamente. A mesma chave é reutilizada em cada nova tentativa, para que solicitações correspondentes possam reproduzir a resposta mantida. As novas tentativas ficam ativadas por padrão (maxRetries: 2): o cliente tenta novamente em falhas transitórias (429, 5xx exceto 501 e erros de transporte PSR-18), com espera exponencial e variação aleatória, respeitando o cabeçalho Retry-After do servidor. Falhas determinísticas (4xx como 401, 404, 422) nunca são repetidas. Para chaves personalizadas entre chamadas separadas ao SDK e limites de reprodução, consulte Idempotência. Substitua as configurações de idempotência e novas tentativas por chamada:

$bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    subject: 'Hello from Bird',
    html: '<p>My first Bird email.</p>',
    options: new RequestOptions(idempotencyKey: 'order-1234', maxRetries: 0),
);

Erros

Uma chamada com falha lança exceção. MessageBird\Exception\ApiException cobre toda resposta de erro do servidor e carrega status (o status HTTP), type (a categoria geral) e errorCode (o código E##### estável). Uma falha de transporte que esgota o orçamento de retentativas lança MessageBird\Exception\ConnectionException porque nenhuma resposta HTTP existe. Ambas estendem MessageBird\Exception\BirdException, então capture essa para tratar qualquer uma das duas.

try {
    $bird->email->send(
        from: 'Bird <onboarding@messagebird.dev>',
        to: ['delivered@messagebird.dev'],
        subject: 'Hello from Bird',
        html: '<p>My first Bird email.</p>',
    );
} catch (ApiException $e) {
    // The server returned an error response. $status is the HTTP status, $type
    // the coarse category, $errorCode the stable E##### code.
    echo $e->status, ' ', $e->errorCode ?? $e->type ?? 'error';
} catch (ConnectionException $e) {
    // All retry attempts failed, so no HTTP response is available.
    echo 'transport error: ', $e->getMessage();
}

Paginação

Métodos de listagem retornam um Core\Page lazy; iterar com foreach pagina automaticamente pelos cursores, buscando páginas sob demanda:

foreach ($bird->email->list(['status' => 'delivered']) as $message) {
    echo $message->getId(), "\n";
}

Para controle manual de cursor, fetch() retorna uma única página: seus data mais o nextCursor de avanço, que você passa de volta como starting_after para avançar:

$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 page

Escape hatch

Endpoints ainda não disponíveis na superfície tipada são acessíveis via $bird->get / post / put / patch / delete, com a mesma autenticação, retentativas, idempotência e tratamento de URL base:

// The verb methods (get/post/put/patch/delete) run through the same auth,
// retries, idempotency, and base-URL handling as the typed methods; pass a
// path and, for writes, a body array.
$messages = $bird->get('/v1/sms/messages', query: ['limit' => 10]);
$created = $bird->post('/v1/sms/messages', body: [
    'from' => '+15557654321',
    'to' => '+15551234567',
    'text' => 'Your code is 123456.',
    'category' => 'authentication',
]);

Encontre os caminhos na referência do API.

Webhooks

Verifique a assinatura Standard Webhooks de um webhook recebido e obtenha o evento decodificado. Defina o segredo de assinatura no cliente (ou passe por chamada) e passe o corpo bruto da solicitação: a assinatura é calculada sobre os bytes brutos, então fazer parsing antes de verificar é o bug clássico de webhook.

// Pass the raw request body because parsing changes the bytes used to compute
// the signature.
$rawBody = file_get_contents('php://input') ?: '';
try {
    $event = $bird->webhooks->unwrap($rawBody, getallheaders());
    // $event is the decoded payload as an array; branch on $event['type'].
    echo $event['type'];
} catch (WebhookVerificationError) {
    http_response_code(400); // bad signature, stale timestamp, or missing/malformed headers
}

Próximos passos

• Quickstart de e-mail em PHP: um envio de ponta a ponta executável.
• Conceitos do SDK: o modelo de retentativa, paginação e região compartilhado entre SDKs.
• Referência do API: todas as operações, com exemplos em PHP.