README

介绍

MessageX 邮件 API 的官方 SDK。其目标是提供在 PHP 中与 MessageX 邮件服务的简单集成，并使用这些服务构建强大可靠的应用程序和软件。我们希望这个 SDK 由社区驱动并由我们领导。您可以通过 composer 安装 SDK 或下载 zip 文件来快速开始。

请求大小

发送附件时没有显式的文件大小限制。大于 30MB 的请求将被拒绝，并返回 HTTP 417 状态码。

错误处理

SDK 中的所有异常都扩展了基类 MxException，以便更容易处理由 SDK 引起的所有异常。对于更精细的错误处理，邮件服务有其自己的基异常 EmailException。

传输错误

在发送请求时，MessageX PHP SDK 使用 Guzzle HTTP 客户端。当 API 返回的状态码不是 2* 时，Guzzle 将根据状态码组（服务器端、客户端）抛出异常。SDK 中不处理与 Guzzle 相关的异常。

先决条件

PHP >= 5.6
MessageX 账户的 API 密钥和密钥

安装

Composer

将以下内容添加到 composer.json 文件中

    {
        "require": {
            "messagex/email-php-sdk": "~1.0"
        }
    }

或从 CLI 运行

composer require messagex/email-php-sdk

快速入门

发送邮件

以下是一个使用 SDK 发送基本邮件所需的最小代码示例。

require 'vendor/autoload.php';

use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body\Body;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
        'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
    ]);

$emailClient->sendEmail(
    (new Email('John Doe <johndoe@example.com>', ['Jane Doe <janedoe@example.com>']))
        ->setSubject('Greetings')
        ->addBody(new Body('text/plain', 'Hi Jane))
);

接收者或发送者的名称可以使用上面的代码示例中显示的表示法添加。添加名称不是必需的，仅添加电子邮件地址也是支持的。目前，仅支持以下内容类型用于电子邮件正文

text/html
text/plain

添加 CC 和 BCC

添加 CC 和 BCC 与第一个示例中的规则相同。

require 'vendor/autoload.php';

use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body\Body;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
        'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
    ]);

$emailClient->sendEmail(
    (new Email('John Doe <johndoe@example.com>', ['Jane Doe <janedoe@example.com>']))
        ->setSubject('Greetings')
        ->addBcc(['John Doe <bcc@example.com>'])
        ->addCc(['John Doe <cc@example.com>'])
        ->addBody(new Body('text/plain', 'Hi Jane'))
);

关于电子邮件地址和名称的规则与第一个示例相同。

添加附件

您可以根据以下示例向电子邮件添加一个或多个附件

require 'vendor/autoload.php';

use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body\Body;
use MessageX\Service\Email\ValueObject\Attachment\Attachment;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
        'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
    ]);

$emailClient->sendEmail(
    (new Email('John Doe <johndoe@example.com>', ['Jane Doe <janedoe@example.com>']))
        //... Code removed
        ->addAttachment(Attachment::fromFile('path/to/file.pdf'))
);

自定义标签

标签是与电子邮件关联的自定义文本标签。可以添加的最大标签数是 5。如以下示例所示添加自定义标签

require 'vendor/autoload.php';

use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body\Body;
use MessageX\Service\Email\ValueObject\Attachment\Attachment;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
        'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
    ]);

$emailClient->sendEmail(
    (new Email('John Doe <johndoe@example.com>', ['Jane Doe <janedoe@example.com>']))
        //... Code removed
        ->addTag('Tag1')
);

自定义头信息

还将添加自定义头信息到电子邮件并发送给收件人。可以添加的最大自定义头信息数是 5。如以下示例所示添加自定义头信息

require 'vendor/autoload.php';

use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body\Body;
use MessageX\Service\Email\ValueObject\Attachment\Attachment;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
        'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
    ]);

$emailClient->sendEmail(
    (new Email('John Doe <johndoe@example.com>', ['Jane Doe <janedoe@example.com>']))
        //... Code removed
        ->addHeader('X-Custom-Header', 'Value')
);

邮件合并

属性表示电子邮件正文中占位符字符串的属性，每个属性的值是所有收件人的替换数组。每个占位符的替换数量必须与收件人的数量匹配。每个占位符的替换顺序必须与收件人的顺序匹配。邮件合并可以如以下示例所示添加

require 'vendor/autoload.php';

use MessageX\Service\Email\ValueObject\Email;
use MessageX\Service\Email\ValueObject\Body\Body;
use MessageX\Service\Email\ValueObject\Attachment\Attachment;
use MessageX\Service\Email\EmailClient;

$emailClient = new EmailClient([
        'credentials' => ['key' => 'XXXXX', 'secret' => 'XXXXX']
    ]);

$emailClient->sendEmail(
    (new Email('John Doe <johndoe@example.com>', ['Jane Doe <janedoe@example.com>', 'Alice Doe <alicedoe@example.com>']))
        //... Code removed
        ->addBody(new Body('text/plain', 'Hi {{name}}'))
        ->addSubstitution('name', ['Jane', 'Alice'])
);

messagex / email-php-sdk

维护者

详细信息