PHP SDK

messagebird/sdk est le SDK PHP officiel pour le API Bird : une surface typée, écrite à la main, au-dessus d'une couche réseau générée. Il cible PHP 8.2+ et est synchrone ; HTTP passe par n'importe quel client PSR-18 que vous utilisez déjà (Guzzle, Symfony HttpClient, …), découvert automatiquement. Cette page couvre le client lui-même ; pour envoyer un e-mail de bout en bout, commencez par le quickstart e-mail PHP.

Installation

composer require messagebird/sdk

Le package est publié sous le nom messagebird/sdk sur Packagist.

Construire un client

$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()
);

Seule la clé API est requise. La région est déduite du préfixe bk_{region}_ de la clé (une clé bk_eu1_… est dirigée vers https://eu1.platform.bird.com), donc la plupart des clients sont construits avec la clé seule ; consultez l'inférence de région pour les règles. baseUrl remplace entièrement la région (local ou auto-hébergé). Les valeurs par défaut de canal définies ici (par exemple email: new EmailDefaults(from: "hello@acme.com")) rendent ce champ optionnel à chaque envoi, et webhookSecret est le secret avec lequel $bird->webhooks->unwrap() vérifie. Configurez un timeout par requête sur le client PSR-18 que vous passez à Bird. PSR-18 n'a pas de timeout portable, donc c'est le transport qui gère ce paramètre.

Premier appel

$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();

L'appel renvoie directement le résultat API : ici un message e-mail avec son em_* id. Pour un guide exécutable, suivez le quickstart PHP.

Conception à deux couches

Le SDK combine des couches générées et écrites à la main. Les types réseau sous MessageBird\Wire proviennent de la spécification OpenAPI de Bird via jane-php, garantissant la conformité des structures de requête et de réponse au contrat. La couche écrite à la main fournit $bird->email->send(...), les réessais, l'idempotence, la pagination, les erreurs et la vérification des webhooks. Les champs réseau passent tels quels dans snake_case, comme category et created_at. Seuls les identifiants définis par SDK, y compris les noms de méthodes et d'options comme idempotencyKey, utilisent camelCase. Les SDK TypeScript, Go et Python partagent cette architecture ; consultez les concepts SDK.

Idempotence et réessais automatiques

Chaque mutation (POST, PUT, PATCH, DELETE) reçoit un en-tête Idempotency-Key généré automatiquement. Cette même clé est réutilisée à chaque nouvelle tentative afin que les requêtes identiques puissent restituer la réponse conservée. Les nouvelles tentatives sont activées par défaut (maxRetries: 2) : le client réessaie les échecs transitoires (429, 5xx sauf 501 et erreurs de transport PSR-18) avec un délai exponentiel et une variation aléatoire, en respectant l’en-tête Retry-After du serveur. Les échecs déterministes (4xx comme 401, 404, 422) ne sont jamais réessayés. Pour les clés personnalisées entre des appels distincts au SDK et les limites de restitution, consultez Idempotence. Remplacez les paramètres d’idempotence et de nouvelle tentative pour chaque appel :

$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),
);

Erreurs

Un appel échoué lève une exception. MessageBird\Exception\ApiException couvre chaque réponse d'erreur du serveur et contient status (le statut HTTP), type (la catégorie générale) et errorCode (le code E##### stable). Un échec de transport qui épuise le budget de réessais lève MessageBird\Exception\ConnectionException à la place, car aucune réponse HTTP n'existe. Les deux étendent MessageBird\Exception\BirdException, donc interceptez celui-ci pour gérer les deux cas.

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

Pagination

Les méthodes de liste renvoient un Core\Page paresseux ; l'itérer avec foreach pagine automatiquement à travers les curseurs, en récupérant les pages à la demande :

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

Pour un contrôle manuel du curseur, fetch() renvoie une seule page : ses data plus le nextCursor suivant, que vous repassez comme starting_after pour avancer :

$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

Échappatoire

Les endpoints pas encore disponibles sur la surface typée sont accessibles via $bird->get / post / put / patch / delete, avec la même authentification, les mêmes réessais, la même idempotence et la même gestion de l'URL de 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',
]);

Retrouvez les chemins dans la référence API.

Webhooks

Vérifiez la signature Standard Webhooks d'un webhook reçu et obtenez l'événement décodé. Définissez le secret de signature sur le client (ou passez-le par appel), et transmettez le corps brut de la requête : la signature porte sur les octets bruts, donc parser avant de vérifier est le bug classique des webhooks.

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

Étapes suivantes

• Quickstart e-mail PHP : un envoi de bout en bout exécutable.
• Concepts SDK : le modèle de réessai, de pagination et de région partagé entre les SDK.
• Référence API : chaque opération, avec des exemples PHP.