README

这是Outkit API的官方PHP客户端。[Outkit](https://outkit.io/)。

安装

Outkit可以作为Composer包使用。将Outkit添加到您的composer.json文件中，如下所示

composer require outkit/php-client
# OR
php composer.phar require outkit/php-client

或者您也可以手动添加，如下所示

{
  "require": {
      "outkit/php-client": "*"
  }
}

使用方法

设置和认证

// Use autolading to be able to use our classes without explicitly requiring them
require __DIR__ . '/vendor/autoload.php';

// Instantiate a client by supplying API credentials
$client = new Outkit\Client(array(
    "key" => "",        // Fill in your API key
    "secret" => "",     // Fill in your API secret
    "passphrase" => ""  // Fill in your API passphrase (not your personal password)
));

您应该想出一个方法将凭证放入您的脚本中，而不是将它们硬编码到源文件中，例如使用环境变量。

提交消息

提交消息进行渲染和/或投递将返回一个包含Outkit ID和状态设置为received（以及一些其他在创建时可以确定的属性）的消息记录。API调用在消息保存到我们的服务器上时立即返回，它不会等待渲染或投递发生（默认情况下 - 下面将介绍同步处理部分）。您可以在任何时候检索消息的状态。我们还支持状态变化时的webhook通知。

// Construct a message record
$messageRecord = array(
    "type" => "email",                   // Message type - 'email' and 'sms' currently supported
    "project" => "my-project",           // Project identifier
    "subject" => "Welcome, Jane!",       // Email subject (optional, can also be set in the template or omitted for SMS messages)
    "template" => "my-template",         // Template identifier
    "to" => "some.name@example.com",     // Recipient address (and optional name)
    "from" => "other.name@example.com",  // Sender address (and optional name)
    "data" => array(
        "name" => "John Doe",
        // ...
        // Add the values for any variables used in the template here
    ),
);

// Then submit it
$message = $client->createMessage($messageRecord);

检索消息

您可以在任何时候检索消息的状态和数据。在消息被渲染后，我们还将返回适用的渲染字段（对于电子邮件，为subject、html_body和text_body，对于短信为text_body），以便您可以确切地看到发送的内容。

$message = $client->getMessage("some-id");

返回值

这两个API调用都返回一个PHP stdClass对象，其中包含有关提交/查询的消息的信息。任何给定时间具有内容的字段取决于提交的字段和消息的当前状态。所有JSON对象和数组都转换为PHP stdClasses和数组。

object(stdClass){
    "type" => "email",
    "id" => "578b072e-79e4-441e-b696-784aa744bf6e",
    "project" => "my-project",
    "template" => "my-welcome",
    "to" => "some.name@example.com",
    "from" => "other.name@example.com",
    "status" => "received",
    "subject" => "Welcome, Jane!",
    "html_body" => null,
    "text_body" => null,
    "data" => null,
    "created_at" => "2017-07-21T19:17:35.383277Z",
    "failed_at" => null,
    "queued_at" => null,
    "delivered_at" => null,
    "done" => false,
}

因此，如果上述内容存储在$message中，您可以通过$message->status访问status。

渲染消息

为了支持使用Outkit基础设施渲染消息，但由您自己发送，您可以在消息记录中指定"render_only" => true。

一旦消息被渲染，其数据将包含一个text_body字段（所有类型），以及电子邮件的subject和html_body字段。然后可以直接将这些内容提供给Mailgun客户端或SMTP服务器。下面将详细介绍。

同步处理

对于某些用例（例如从脚本中发送电子邮件、使用Outkit作为渲染器等），可能希望API调用同步操作 - 即立即尝试渲染/投递，而不是排队，并在API调用的数据中返回渲染后的消息及其（可选）投递状态。这可以通过在提交的消息中设置"sync" => true来实现。

请注意，这将产生额外的费用（有关详细信息，请参阅我们的定价页面），并且每个Outkit客户每月只允许有限数量的此类请求（目前为100,000次），因为这些请求对我们来说更难以扩展且成本更高。需要额外同步请求的客户可以联系支持以增加其每月限制。

消息生命周期

提交的消息通常经过以下阶段，这些阶段反映在status字段中

received - 消息已被接收并保存在我们的数据存储中，等待进一步处理
queued_for_rendering - 消息已排队等待渲染
rendered - 模板的主题和HTML/文本已被渲染并合并到提交的数据中
queued_for_delivery - 消息已排队等待发送
delivered - 消息已成功发送到后端

通常，消息会以毫秒为单位通过所有阶段，但有时可能需要更长一点的时间。

请注意，不同的消息可能具有不同的状态。例如，设置了render_only标记的消息永远不会排队等待发送或发送。那些提供自己的text_body和html_body而不是使用模板的消息永远不会被渲染，只会被发送。

请注意，delivered状态并不一定意味着消息已发送到最终用户。一旦后端已接受消息，最终发送则由后端负责。大多数后端提供webhooks，如果您需要实际发送的确认。

在出现错误和问题时，您的消息还可能具有一些其他状态

render_error - 我们无法使用提交的数据渲染模板
backend_error - 我们在尝试将消息提交到配置的后端时遇到了错误
internal_error - 我们内部出现了不可恢复的问题（应该是非常罕见的）

如果消息有任何这些状态，status_message字段中将有更多信息。此外，您可以在response字段中检查完整的后端响应。

所有消息都有一个done标志（true或false），表示我们是否已完成对其的处理。一旦消息完成，无论其状态如何，都不会再发生任何其他操作。

关于函数名的说明

消息的函数名（getMessage和createMessage）是故意通用的，以与API的未来扩展（比如createProject）保持一致。所以尽管您可能感觉您正在提交或发送消息（我们在自己的文档中经常使用这样的术语），在API术语中，您始终只是在执行createMessage。

您可能会将我们的函数包装在您自己的sendSms或enqueueEmail或任何其他函数中，所以这不应该是个大问题。我们认为，在处理API及其客户端时，一致性胜于语言准确性。

待办事项

添加带有模拟的正确测试
添加一种访问完整响应的方式

outkit / php-client

维护者

详细信息