---
title: PHP SDK
description: 用 billionsend-php 包在 PHP 里发送邮件、使用收件箱、验证 Webhook，覆盖全部 API 操作，内置重试与幂等键。
ai:
  exclude: true
---

`billionsend/billionsend-php` 包是 BillionSend 面向 PHP 的客户端。它覆盖 [API 参考](/docs/zh-hans/api-reference)里的全部操作：发送、域名、联系人、群发、模板、Webhook、带会话和草稿的收件箱、实时的收件箱事件，以及 Agent 注册。源码在 GitHub 上的 [billionsend/billionsend-php](https://github.com/billionsend/billionsend-php)。

## 安装

需要 PHP 8.1 或更高版本，并启用 `curl` 和 `json` 扩展，不需要别的。

```sh
composer require billionsend/billionsend-php
```

## 发送邮件

```php
use BillionSend\Client;

$client = new Client(); // 读取 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_...')` 直接传入密钥。第二个参数设置其余选项：`'base_url'`、`'timeout'`（每次尝试的秒数，默认 60）、`'max_retries'`、`'headers'` 和 `'transport'`（任何 `BillionSend\Transport`，用来通过你自己的 HTTP 栈发送）。`BILLIONSEND_BASE_URL` 可以覆盖 API 地址。

## 方法命名

每个操作都是一个方法，名字取自它在 [API 参考](/docs/zh-hans/api-reference)里的 id，用点分隔的路径变成一串服务：`emails.send` 是 `$client->emails->send()`，`emails.receiving.attachments.list` 是 `$client->emails->receiving->attachments->list()`。`emails.metrics` 是 `$client->emails->metrics->get()`，旁边还有 `->links()`、`->countries()` 和 `->clients()`。

一个方法依次接收：路径参数（按顺序）、请求体、查询和请求头参数，最后是这次调用的选项。请求体和响应都是关联数组，字段名就是 API 自己的字段名，所以 API 参考里的说明可以逐字段对应。

## 幂等与重试

八个发送操作（`emails->send`、`emails->batch`、收到邮件的回复与转发、`inboxes->send`、`inboxes->drafts->send`、会话的回复与转发）总是会带上 `Idempotency-Key`。如果没有 `'idempotency_key'`，每次调用会自己生成一个，它的重试沿用这个密钥，所以超时后的重试不会重复发送；你自己的密钥还能让另一个进程里的重复调用也保持安全。

值得重试的失败默认会重试两次：429、5xx、超时、网络错误，以及同一个密钥的第一次请求仍在运行时返回的 `409 concurrent_idempotent_requests`。只有可以安全重复的请求才会重试：`GET`、`PUT`、`DELETE` 和发送操作。客户端按 `Retry-After` 的要求等待，最长一分钟，其余情况从 0.5 s 起按指数退避，最多 8 s。每个方法的最后一个参数都接受 `'idempotency_key'`、`'headers'`、`'timeout'`、`'max_retries'` 和 `'response_headers' => &$headers`，只对这次调用生效。

## 错误

失败的调用会抛出 `ValidationError`（400、422）、`AuthenticationError`（401，或没有配置密钥）、`PermissionDeniedError`（403）、`NotFoundError`（404）、`ConflictError`（409）、`RateLimitError`（429，`getRetryAfter()` 以秒为单位）、`APIError`（5xx）、`APIConnectionError`（没有响应）或 `APITimeoutError`（这次尝试超时）。它们都在 `BillionSend\Exception` 里，并继承自 `BillionSendError`，带有 `getStatusCode()`、`getErrorName()`（API 的错误名）、`getMessage()` 和 `getRequestId()`；`getRequestId()` 返回响应的 `x-request-id`，也就是这个请求在控制台日志页面上的 id。

```php
use BillionSend\Exception\BillionSendError;
use BillionSend\Exception\NotFoundError;

try {
    $email = $client->emails->get($id);
} catch (NotFoundError) {
    // 没有这封邮件
} catch (BillionSendError $e) {
    error_log(sprintf('%s %s: %s (request %s)', $e->getStatusCode(), $e->getErrorName(), $e->getMessage(), $e->getRequestId()));
}
```

## 列表

列表方法返回一页。每个游标列表还有一个 `...All()` 生成器，会在迭代过程中获取后续的页；设置了 `'before'` 时则向后翻：

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

## Agent 的收件箱

在[事件流](/docs/zh-hans/inboxes)上等待新邮件，并在它所在的会话里回复：

```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; // 事件可能有缺失：重新读取会话
    }
    $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']}"],
    );
}
```

连接断开时，事件流会带着 `Last-Event-ID` 重新连接，并补上错过的事件；保存 `$stream->lastEventId()`，再把它作为 `'last_event_id'` 选项传回去，就能在重启之后继续。从 24 小时之前的位置恢复时，会收到一次 `StreamGapEvent`。选项 `'max_reconnects'`（默认 5）、`'reconnect_delay'` 和 `'reconnect' => false` 用来调整重连行为。单个收件箱的事件流在该收件箱被删除或过期后结束；`$client->inboxes->events->stream()` 会跟随这把密钥能读取的所有收件箱。

## 验证 Webhook

`Webhook::verify` 用端点的 `whsec_` 密钥检查一次 [Webhook](/docs/zh-hans/concepts/webhooks) 投递的签名和时间戳，并返回解析后的事件。传入的请求体必须与收到时完全一致：

```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') {
    // ...
}
```

超过五分钟的投递会被拒绝，密钥轮换期间，新旧两个密钥都能通过验证。

## Agent 注册

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

这个调用不需要 API 密钥；响应里带有新的密钥和收件箱。未认领的账号可以做什么，见 [Agent 注册](/docs/zh-hans/agent-signup)。
