PHP SDK

messagebird/sdk es el SDK oficial de PHP para la API de Bird: una superficie tipada, escrita a mano sobre una capa de transporte generada. Está dirigido a PHP 8.2+ y es síncrono; HTTP pasa por cualquier cliente PSR-18 que ya tengas (Guzzle, Symfony HttpClient, …), descubierto automáticamente. Esta página cubre el cliente en sí; para enviar un correo electrónico de principio a fin, comienza con el quickstart de email en PHP.

Instalación

composer require messagebird/sdk

El paquete está publicado como messagebird/sdk en Packagist.

Construir un 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()
);

Solo la clave API es obligatoria. La región se infiere del prefijo bk_{region}_ de la clave (una clave bk_eu1_… se dirige a https://eu1.platform.bird.com), así que la mayoría de los clientes se construyen solo con la clave; consulta inferencia de región para las reglas. baseUrl sobrescribe la región por completo (local o autoalojado). Los valores predeterminados de canal configurados aquí (por ejemplo email: new EmailDefaults(from: "hello@acme.com")) hacen que ese campo sea opcional en cada envío, y webhookSecret es el secreto con el que $bird->webhooks->unwrap() verifica. Configura un timeout por solicitud en el cliente PSR-18 que pasas a Bird. PSR-18 no tiene un timeout portable, así que el transporte controla esa configuración.

Primera llamada

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

La llamada devuelve directamente el resultado API: aquí un mensaje de correo electrónico con su id em_*. Para un recorrido ejecutable, sigue el quickstart de PHP.

Diseño de dos capas

El SDK combina capas generadas y escritas a mano. Los tipos de transporte en MessageBird\Wire provienen de la especificación OpenAPI de Bird a través de jane-php, manteniendo las formas de solicitud y respuesta fieles al contrato. La capa escrita a mano proporciona $bird->email->send(...), reintentos, idempotencia, paginación, errores y verificación de webhooks. Los campos de transporte pasan literalmente en snake_case, como category y created_at. Solo los identificadores definidos por SDK, incluidos nombres de métodos y opciones como idempotencyKey, usan camelCase. Los SDKs de TypeScript, Go y Python comparten esta arquitectura; consulta conceptos de SDK.

Idempotencia y reintentos automáticos

Cada mutación (POST, PUT, PATCH, DELETE) recibe una cabecera Idempotency-Key generada automáticamente, y esa misma clave se reutiliza en cada reintento para que las solicitudes coincidentes puedan reproducir la respuesta conservada. Los reintentos están activados de forma predeterminada (maxRetries: 2): el cliente reintenta los fallos transitorios (429, 5xx excepto 501 y errores de transporte PSR-18) con espera exponencial y variación aleatoria, respetando la cabecera Retry-After del servidor. Los fallos deterministas (4xx como 401, 404, 422) nunca se reintentan. Para claves personalizadas entre llamadas independientes al SDK y límites de reproducción, consulta Idempotencia. Configura la idempotencia y los reintentos por llamada:

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

Errores

Una llamada fallida lanza una excepción. MessageBird\Exception\ApiException cubre toda respuesta de error del servidor y contiene status (el estado HTTP), type (la categoría general) y errorCode (el código estable de E#####). Un fallo de transporte que agota el presupuesto de reintentos lanza MessageBird\Exception\ConnectionException en su lugar, porque no existe una respuesta HTTP. Ambas extienden MessageBird\Exception\BirdException, así que captura esa para manejar cualquiera de las dos.

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

Paginación

Los métodos de listado devuelven un Core\Page perezoso; iterarlo con foreach pagina automáticamente a través de cursores, obteniendo páginas bajo demanda:

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

Para control manual de cursor, fetch() devuelve una sola página: su data más el cursor de avance nextCursor, que pasas de vuelta como starting_after para avanzar:

$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

Alternativa directa

Los endpoints que aún no están en la superficie tipada son accesibles a través de $bird->get / post / put / patch / delete, con la misma autenticación, reintentos, idempotencia y manejo 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',
]);

Encuentra las rutas en la referencia de API.

Webhooks

Verifica la firma Standard Webhooks de un webhook recibido y obtén el evento decodificado. Configura el secreto de firma en el cliente (o pásalo por llamada), y pasa el cuerpo crudo de la solicitud: la firma se calcula sobre los bytes crudos, así que parsear antes de verificar es el error clásico de 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
}

Próximos pasos

• Quickstart de email en PHP: un envío ejecutable de principio a fin.
• Conceptos de SDK: el modelo de reintentos, paginación y región compartido entre SDKs.
• Referencia de API: todas las operaciones, con ejemplos en PHP.