---
title: SDK para PHP
description: Use o BillionSend em PHP com o pacote billionsend/billionsend-php.
ai:
  exclude: true
---

O pacote `billionsend/billionsend-php` é o cliente do BillionSend para PHP. Ele cobre todas as operações da [referência da API](/docs/pt-br/api-reference): 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](https://github.com/billionsend/billionsend-php) no GitHub.

## Instalar

Requer PHP 8.1 ou mais recente com as extensões `curl` e `json`, e nada mais.

```sh
composer require billionsend/billionsend-php:^0.1
```

## Enviar um e-mail

```php
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](/docs/pt-br/api-reference), 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.

```php
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:

```php
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](/docs/pt-br/inboxes) e responda na conversa:

```php
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](/docs/pt-br/concepts/webhooks) com o segredo `whsec_` do endpoint e devolve o evento já interpretado. Passe o corpo exatamente como chegou:

```php
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.
