SDK para PHP
Use o BillionSend em PHP com o pacote billionsend/billionsend-php.
O pacote billionsend/billionsend-php é o cliente do BillionSend para PHP. Ele cobre todas as operações da referência da API: envio, domínios, contatos, broadcasts, templates, webhooks, caixas de entrada com suas conversas e rascunhos, eventos das caixas de entrada em tempo real e cadastro de agentes. O código-fonte está em billionsend/billionsend-php no GitHub.
Instalar
Requer PHP 8.1 ou mais recente com as extensões curl e json, e nada mais.
composer require billionsend/billionsend-php:^0.1
Enviar um e-mail
use BillionSend\Client;
$client = new Client(); // reads BILLIONSEND_API_KEY
$sent = $client->emails->send([
'from' => 'Acme <hello@acme.dev>',
'to' => ['ana@example.com'],
'subject' => 'Welcome to Acme',
'html' => '<p>Glad you are here.</p>',
], ['idempotency_key' => 'welcome/ana']);
echo $sent['id'];
new Client('bs_...') recebe a chave diretamente. O segundo argumento define o resto: 'base_url', 'timeout' (segundos por tentativa, padrão de 60), 'max_retries', 'headers' e 'transport' (qualquer BillionSend\Transport, para enviar pela sua própria pilha HTTP). BILLIONSEND_BASE_URL substitui a URL da API.
Nomes dos métodos
Cada operação é um método com o nome do seu id na referência da API, o caminho com pontos virando uma cadeia de serviços: emails.send é $client->emails->send(), emails.receiving.attachments.list é $client->emails->receiving->attachments->list(). emails.metrics é $client->emails->metrics->get(), ao lado de ->links(), ->countries() e ->clients().
Um método recebe os parâmetros de caminho em ordem, o corpo da requisição, os parâmetros de consulta e de cabeçalho e por fim as opções da chamada. Corpos e respostas são arrays associativos com os nomes de campo da própria API, então a referência da API os descreve campo a campo.
Idempotência e novas tentativas
As oito operações de envio (emails->send, emails->batch, respostas e encaminhamentos de e-mails recebidos, inboxes->send, inboxes->drafts->send, respostas e encaminhamentos em conversas) sempre enviam um Idempotency-Key. Sem 'idempotency_key', cada chamada cria uma chave que as suas novas tentativas reutilizam, então uma nova tentativa depois de um timeout nunca envia duas vezes; a sua própria chave também deixa segura uma repetição vinda de outro processo.
Falhas que valem nova tentativa são repetidas duas vezes por padrão: 429, 5xx, timeouts, erros de rede e o 409 concurrent_idempotent_requests respondido enquanto a primeira tentativa com a mesma chave ainda está em andamento. Só são repetidas as requisições seguras de repetir: GET, PUT, DELETE e as operações de envio. O cliente espera o que o Retry-After pede, até um minuto, e senão recua exponencialmente de 0,5 s até 8 s. O último argumento de todo método aceita 'idempotency_key', 'headers', 'timeout', 'max_retries' e 'response_headers' => &$headers para aquela chamada.
Erros
Uma chamada que falha lança ValidationError (400, 422), AuthenticationError (401, ou nenhuma chave configurada), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429, com getRetryAfter() em segundos), APIError (5xx), APIConnectionError (sem resposta) ou APITimeoutError (a tentativa estourou o tempo). Todas ficam em BillionSend\Exception e estendem BillionSendError, com getStatusCode(), getErrorName() (o nome do erro na API), getMessage() e getRequestId(), o x-request-id da resposta, que é o id da requisição na página Logs do painel.
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
Os métodos de lista devolvem uma página. Toda lista com cursor também tem um gerador ...All() que busca as páginas seguintes conforme avança, para trás quando 'before' está definido:
foreach ($client->contacts->listAll(['limit' => 100]) as $contact) {
echo $contact['email'], "\n";
}
A caixa de entrada de um agente
Espere e-mails novos no fluxo de eventos e responda na conversa:
use BillionSend\StreamGapEvent;
$stream = $client->inboxes->events->streamInbox('support@acme.dev', ['types' => 'inbox.email.received']);
foreach ($stream as $event) {
if ($event instanceof StreamGapEvent) {
continue; // events may be missing: read the threads again
}
$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']}"],
);
}
O fluxo se reconecta com Last-Event-ID quando a conexão cai e reenvia o que perdeu; guarde $stream->lastEventId() e passe-o de volta na opção 'last_event_id' para retomar depois de reiniciar. Um StreamGapEvent chega uma vez quando o fluxo é retomado de mais de 24 horas atrás. As opções 'max_reconnects' (padrão 5), 'reconnect_delay' e 'reconnect' => false ajustam a reconexão. O fluxo de uma caixa termina depois que essa caixa é excluída ou expira; $client->inboxes->events->stream() acompanha todas as caixas que a chave pode ler.
Verificar webhooks
Webhook::verify confere a assinatura e o horário de uma entrega de webhook com o segredo whsec_ do endpoint e devolve o evento já interpretado. Passe o corpo exatamente como chegou:
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') {
// ...
}
Uma entrega com mais de cinco minutos é recusada, e durante a rotação de um segredo qualquer um dos dois verifica.