跳到内容
Esc
↑↓导航↵打开⌘J预览
本页内容

PHP SDK

用 billionsend-php 包在 PHP 里发送邮件、使用收件箱、验证 Webhook,覆盖全部 API 操作,内置重试与幂等键。

billionsend/billionsend-php 包是 BillionSend 面向 PHP 的客户端。它覆盖 API 参考里的全部操作:发送、域名、联系人、群发、模板、Webhook、带会话和草稿的收件箱、实时的收件箱事件,以及 Agent 注册。源码在 GitHub 上的 billionsend/billionsend-php。

安装

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

composer require billionsend/billionsend-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 参考里的 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。

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' 时则向后翻:

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

Agent 的收件箱

在事件流上等待新邮件,并在它所在的会话里回复:

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 投递的签名和时间戳,并返回解析后的事件。传入的请求体必须与收到时完全一致:

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 注册

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

这个调用不需要 API 密钥;响应里带有新的密钥和收件箱。未认领的账号可以做什么,见 Agent 注册。

这个页面有帮助吗?