README

这个库帮助您使用 PHP 7.2（及以上）中的 Postal API 发送电子邮件、获取消息详情和交付以及实现事件来处理服务器 Webhook。

它使用 GuzzleHTTP 客户端和 PSR-7：HTTP-PSR7 接口。

安装

使用 Composer 安装库

composer require rnevarezc/postal

用法

使用客户端

您需要从您的 Postal 安装中获取 API 凭证才能使用 API 客户端。

// Create a new Postal client using the server key of your Postal Installation.
$client = new \Postal\Client('https://postal.yourdomain.com', 'your-api-key');

// Optional: You can add any aditional Headers for your API installation (Maybe Authorization)
// You just add an array of headers:
$headers = [
    'Authorization' => 'Basic RTYtaO54BGBtcG9yYWwyMDIw'
];

$client = new \Postal\Client('https://postal.yourdomain.com', 'your-api-key', $headers);

// Or you can add them manually to a Client Instance:
$client->addHeaders($headers);

发送电子邮件

发送电子邮件很简单。您可以按照以下示例操作

// Create a new Mail message with a Hash of attributes:
$mail = new \Postal\Mail\Mail([
    'to' => ['recipient@mail.com', 'rafael@example.com'],
    'cc' => 'me@github.com',
    'from' => 'me@mail.com',
    'subject' => 'A Postal Email!',
    'plain_body' => 'This is a test of new Postal Client',
    'html_body' => '<p>This is a HTML body!</p>'
]);

或创建一个新的邮件消息并手动添加每个邮件属性

$mail = new \Postal\Mail\Mail;

$mail->addTo('recipient@example.com');

// You can Add TO, CC, BCC recipients using strings or arrays:
$mail->addTo(['john@example.com', 'testing@example.com']);
$mail->addCc('test@example.com');

// Add any custom headers
$mail->addHeader('X-PHP-Test', 'value');

// Set the Subject, Plain Body, HTML Body, from, and sender manually:
$mail->setSubject('My new subject');
$mail->setPlainBody('This is a new text');
$mail->setHtmlBody('<p>This is a new text</p>');

// Finally, when you are ready, send the Message using the client.
// You can capture the API Response if you like.
$response = $client->send($mail);
// This is a instance of \Postal\Response\Response;

如果您想捕获邮件的每个收件人分发的消息，您可以这样做

//This will return a Hash of 'recipient' => \Postal\Message\Message Instance
$messages = $mail->getMessages();

foreach ($messages as $recipient => $message){
    $recipient = $recipient; //recipient@mail.com
    $id = $message->getId(); // Ex.: 653621
    $token = $message->getToken() // abcdef123
}

获取消息详情

您可以使用客户端获取消息的详情。您只需要消息 ID

// Get the Details of the Message: 653621 of the previous example:
$response = $client->getMessageDetails(653621);

// Then use the details:
$data = $response->getData(); // This is an array of the Message Details.

// Additionaly you can specify individual _expansions for the Message Detail,
// or use "true" to retreive them all:
$response = $client->getMessageDetails(653621, ['status', 'details', 'inspection']);

// OR:
$response = $client->getMessageDetails(653621, true);
// This will get all the expansions provided by the Postal API.

获取消息交付

您可以使用客户端获取消息的交付。您只需要消息 ID

// Get the Details of the Message: 653621 of the previous example:
$response = $client->getMessageDeliveries(653621);
// This will return a \Postal\Response\Response instance

// Then use the deliveries structure:
$data = $response->getData(); // This is an array of the Message Deliveries

事件和 Webhook！

此库支持 Postal 安装可以通过 Webhook 发送的任何类型的有效载荷。

您必须配置您的 Postal 安装将事件发送到您选择的 URL，才能使用此库。

有关 Webhook 和有效载荷的更多信息，请参阅 Postal 文档

消息状态事件、退订事件和点击事件

消息状态事件都接收相同的有效载荷（具有不同的数据），基于消息的状态。

• MessageSent - 当消息成功投递时

• MessageDelayed - 当消息的投递被延迟时。

• MessageDeliveryFailed - 当消息无法投递时。

• MessageHeld - 当消息被保留时。

• 如果消息被退订，您将收到 MessageBounced 事件。

• 如果您启用了点击跟踪，则 MessageLinkClicked 事件将告诉您用户已点击了您的电子邮件中的链接。

Postal\Events\Message\Events 类是一个工厂，可以解析这些事件中的任何一种的有效载荷并构建正确的事件实现。

在处理程序（或控制器）中捕获这些事件非常简单。您可以在应用程序中定义一个类并像这样捕获请求

...
use Postal\Events\Message\Events;
use Postal\Events\Message\MessageEvent;
use Psr\Http\Message\RequestInterface;

class MessageEventController extends Controller
{
    /**
     * Handle Message Event Webhooks
     *
     * Postal sends the events via a POST method.
     *
     * @param Request $request
     * ...
     */
    public function post(RequestInterface $request) {

       // Here we capture the Event payload provided in the PSR-7
       // Request and parse it into an Event using the Message Events Factory.

       // @var \Postal\Events\Message\MessageEvent
       $event = Events::fromRequest($request);

       // ... Do some Stuff...
    }
}
...

如果您以其他方式捕获 POST 有效载荷，可以直接将该有效载荷发送到工厂以构建事件

$event = Events::fromPayload($array);

如果提供无效的有效载荷，将抛出 \Postal\Exceptions\InvalidEventPayloadException

使用 MessageEvent。

根据事件类型，您将获得 MessageEvent 接口 的具体实现。定义的类型（及其类）与 Postal 提供的类型相同

...
interface MessageEvent extends Event
{
    const SENT = 'Sent';
    const DELAYED = 'Delayed';
    const DELIVERY_FAILED = 'DeliveryFailed';
    const HELD = 'Held';
    const BOUNCED = 'Bounced';
    const CLICKED = 'LinkClicked';
    ...
}

• getMessage() : 返回与事件关联的 \Postal\Message\Message 实例。
• getType() : 返回事件的类型。
• toArray() : 返回事件的数组表示。

消息退订事件

• getBounce(): 返回带有退订消息的 \Postal\Message\Message 实例。

服务器事件

如果您想捕获 DomainDNSError 事件，可以使用该特定事件类

$event = DomainDNSError::fromPayload($array);

同样地，如果您想捕获任何类型的SendLimit事件，您可以通过在工厂类中定义的静态方法来实现。

$event = SendLimitApproaching::fromPayload($array);

或者

$event = SendLimitExceeded::fromPayload($array);

$event变量将根据有效载荷具有正确的事件。

强烈建议根据事件类型使用不同的处理程序（或控制器），并且不要使用通用的webhook URL来处理它们！

API信息

您可以在Postal项目维基中获取有关Postal API和有效载荷的更多信息。