Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

SDK de PHP

Envía emails, trabaja con una bandeja de entrada y verifica webhooks desde PHP con el paquete billionsend-php: toda la API, reintentos y claves de idempotencia.

El paquete billionsend/billionsend-php es el cliente de BillionSend para PHP. Cubre todas las operaciones de la referencia de la API: envío, dominios, contactos, envíos masivos, plantillas, webhooks, bandejas de entrada con sus hilos y borradores, eventos de bandeja en tiempo real y registro de agentes. El código fuente está en billionsend/billionsend-php, en GitHub.

Instalar

Requiere PHP 8.1 o superior con las extensiones curl y json, y nada más.

composer require billionsend/billionsend-php

Enviar un email

use BillionSend\Client;

$client = new Client(); // lee BILLIONSEND_API_KEY

$sent = $client->emails->send([
    'from' => 'Acme <hello@acme.dev>',
    'to' => ['success@simulator.amazonses.com'],
    'subject' => 'Welcome to Acme',
    'html' => '<p>Glad you are here.</p>',
], ['idempotency_key' => 'welcome/ana']);

echo $sent['id'];

new Client('bs_...') recibe la clave directamente. El segundo argumento define el resto: 'base_url', 'timeout' (segundos por intento, 60 por defecto), 'max_retries', 'headers' y 'transport' (cualquier BillionSend\Transport, para enviar a través de tu propia pila HTTP). BILLIONSEND_BASE_URL sustituye la URL de la API.

Nombres de los métodos

Cada operación es un método con el nombre de su id en la referencia de la API: la ruta con puntos se convierte en una cadena de servicios. emails.send es $client->emails->send() y emails.receiving.attachments.list es $client->emails->receiving->attachments->list(). emails.metrics es $client->emails->metrics->get(), junto a ->links(), ->countries() y ->clients().

Un método recibe los parámetros de ruta en orden, el cuerpo de la petición, los parámetros de consulta y de cabecera, y por último las opciones de la llamada. Los cuerpos y las respuestas son arrays asociativos con los nombres de campo propios de la API, así que la referencia de la API los describe campo por campo.

Idempotencia y reintentos

Las ocho operaciones de envío (emails->send, emails->batch, respuestas y reenvíos de correo recibido, inboxes->send, inboxes->drafts->send, respuestas y reenvíos de hilos) siempre mandan un Idempotency-Key. Sin 'idempotency_key', cada llamada se inventa una que sus reintentos reutilizan, así que reintentar tras un timeout nunca envía dos veces. Una clave tuya también hace segura la repetición desde otro proceso.

Los fallos que merecen otro intento se reintentan dos veces por defecto: 429, 5xx, timeouts, errores de red y el 409 concurrent_idempotent_requests que se devuelve mientras el primer intento con la misma clave sigue en curso. Solo se reintentan las peticiones que se pueden repetir sin riesgo: GET, PUT, DELETE y las operaciones de envío. El cliente espera lo que pida Retry-After, hasta un minuto; si no, aumenta la espera de forma exponencial de 0,5 s a 8 s. El último argumento de cada método acepta 'idempotency_key', 'headers', 'timeout', 'max_retries' y 'response_headers' => &$headers para esa llamada.

Errores

Una llamada fallida lanza ValidationError (400, 422), AuthenticationError (401, o no hay clave configurada), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429, con getRetryAfter() en segundos), APIError (5xx), APIConnectionError (sin respuesta) o APITimeoutError (el intento agotó el tiempo). Todos están en BillionSend\Exception y extienden BillionSendError, con getStatusCode(), getErrorName() (el nombre del error de la API), getMessage() y getRequestId(), el x-request-id de la respuesta, que es el id de la petición en la página Registros del panel.

use BillionSend\Exception\BillionSendError;
use BillionSend\Exception\NotFoundError;

try {
    $email = $client->emails->get($id);
} catch (NotFoundError) {
    // no such email
} catch (BillionSendError $e) {
    error_log(sprintf('%s %s: %s (request %s)', $e->getStatusCode(), $e->getErrorName(), $e->getMessage(), $e->getRequestId()));
}

Listas

Los métodos de lista devuelven una página. Cada lista con cursor tiene además un generador ...All() que va pidiendo las páginas siguientes, hacia atrás si se define 'before':

foreach ($client->contacts->listAll(['limit' => 100]) as $contact) {
    echo $contact['email'], "\n";
}

La bandeja de entrada de un agente

Espera email nuevo en el flujo de eventos y responde en su hilo:

use BillionSend\StreamGapEvent;

$stream = $client->inboxes->events->streamInbox('support@acme.dev', ['types' => 'inbox.email.received']);

foreach ($stream as $event) {
    if ($event instanceof StreamGapEvent) {
        continue; // puede faltar algún evento: vuelve a leer los hilos
    }
    $data = $event->payload();
    $client->inboxes->threads->emails->reply(
        $event->inboxId(),
        $data['thread_id'],
        $data['email_id'],
        ['text' => 'Thanks, we are on it.'],
        ['idempotency_key' => "reply/{$data['email_id']}"],
    );
}

El flujo se reconecta con Last-Event-ID cuando se corta la conexión y reenvía lo que se perdió. Guarda $stream->lastEventId() y pásalo de nuevo como opción 'last_event_id' para retomarlo tras un reinicio. Un StreamGapEvent llega una sola vez, cuando el flujo se retoma desde hace más de 24 horas. Las opciones 'max_reconnects' (5 por defecto), 'reconnect_delay' y 'reconnect' => false ajustan la reconexión. El flujo de una bandeja termina cuando esa bandeja se elimina o caduca; $client->inboxes->events->stream() sigue todas las bandejas que la clave puede leer.

Verificar webhooks

Webhook::verify comprueba la firma y la marca de tiempo de una entrega de webhook con el secreto whsec_ del endpoint y devuelve el evento ya interpretado. Pasa el cuerpo exactamente como llegó:

use BillionSend\Exception\WebhookVerificationError;
use BillionSend\Webhook;

try {
    $event = Webhook::verify(file_get_contents('php://input'), getallheaders(), getenv('BILLIONSEND_WEBHOOK_SECRET'));
} catch (WebhookVerificationError) {
    http_response_code(400);
    exit;
}
if ($event['type'] === 'email.bounced') {
    // ...
}

Una entrega de más de cinco minutos se rechaza y, durante la rotación de un secreto, sirve cualquiera de los dos.

Registro de agentes

$signup = (new BillionSend\Client())->agent->signup(['human_email' => 'owner@acme.dev', 'name' => 'Support agent']);
echo $signup['inbox']['email_address'], "\n";

La llamada no necesita clave de API; la respuesta trae la clave nueva y la bandeja de entrada. Consulta Registro de agentes para saber qué puede hacer una cuenta sin reclamar.

¿Te ha resultado útil esta página?