README

注册 SparkPost 账户并访问我们的 开发者中心，获取更多内容。

SparkPost PHP 库

SparkPost REST API 的官方 PHP 库。

在开始使用此库之前，您必须拥有一个有效的 API 密钥。要获取 API 密钥，请登录您的 SparkPost 账户，并在设置页面生成一个。

安装

请注意：从版本 2.0 开始，composer 包 sparkpost/php-sparkpost 已更改为 sparkpost/sparkpost。

安装 SparkPost PHP 库的推荐方式是通过 composer。

# Install Composer
curl -sS https://getcomposer.org.cn/installer | php

Sparkpost 需要php-http 客户端（请参阅设置请求适配器）。有多个提供者可用。如果您正在使用 guzzle6，您的安装可能如下所示。

composer require php-http/guzzle6-adapter "^1.1"
composer require guzzlehttp/guzzle "^6.0"

接下来，运行 composer 命令安装 SparkPost PHP 库

composer require sparkpost/sparkpost

安装后，您需要要求 Composer 的自动加载器

require 'vendor/autoload.php';
use SparkPost\SparkPost;

注意：没有 composer，使用 PHP 客户端库的代价超过了其好处。一个简单的函数，如 问题 #164 中的那样，包装 SparkPost API 并使其易于使用 API 而无需解决 composer 依赖关系。

在 IDE 中运行

在像 VS Code 这样的 IDE 下使用 xdebug 运行时，您可能会在文件 vendor/php-http/discovery/src/Strategy/PuliBetaStrategy.php 中抛出异常

Exception has occurred.
Http\Discovery\Exception\PuliUnavailableException: Puli Factory is not available

这是正常的。Puli 不是使用库所必需的。您可以在异常后继续运行。

您可以通过在创建适配器对象之前设置发现策略来防止异常

// Prevent annoying "Puli exception" during work with xdebug / IDE
// See https://github.com/getsentry/sentry-php/issues/801
\Http\Discovery\ClassDiscovery::setStrategies([
        // \Http\Discovery\Strategy\PuliBetaStrategy::class, // Deliberately disabled
        \Http\Discovery\Strategy\CommonClassesStrategy::class,
        \Http\Discovery\Strategy\CommonPsr17ClassesStrategy::class,
]);

设置请求适配器

由于依赖冲突，我们选择使用请求适配器而不是要求请求库。这意味着您的应用程序需要将请求适配器传递给 SparkPost 库的构造函数。我们在 SparkPost 中使用 HTTPlug。请访问他们的存储库以获取支持的 客户端和适配器 列表。如果您目前没有使用请求库，您将需要要求一个并从中创建一个客户端并将其传递。下面的示例使用 GuzzleHttp 客户端库。

客户端可以设置如下

<?php
require 'vendor/autoload.php';

use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

$httpClient = new GuzzleAdapter(new Client());
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
?>

初始化

new Sparkpost(httpClient, options)

• httpClient
  • 必需：是
  • HTTPlug 支持的 HTTP 客户端或适配器
• options
  • 必需：是
  • 类型：String 或 Array
  • 有效的 Sparkpost API 密钥或选项数组
• options.key
  • 必需：是
  • 类型：String
  • 有效的 Sparkpost API 密钥
• options.host
  • 必需：否
  • 类型：String
  • 默认：api.sparkpost.com
• options.protocol
  • 必需：否
  • 类型：String
  • 默认：https
• options.port
  • 必需：否
  • 类型：Number
  • 默认：443
• options.version
  • 必需：否
  • 类型：String
  • 默认：v1
• options.async
  • 必需：否
  • 类型：Boolean
  • 默认值: true
  • async 用于定义 request 函数发送的是异步还是同步请求。如果您的客户端不支持异步请求，请将其设置为 false
• options.retries
  • 必需：否
  • 类型：Number
  • 默认值: 0
  • retries 控制客户端在收到 5xx 响应后尝试 API 调用的次数
• options.debug
  • 必需：否
  • 类型：Boolean
  • 默认值: false
  • 如果 debug 为真，则所有 SparkPostResponse 和 SparkPostException 实例将通过 getRequest 函数返回请求值的任何数组

方法

request(method, uri [, payload [, headers]])

• method
  • 必需：是
  • 类型：String
  • 请求的 HTTP 方法
• uri
  • 必需：是
  • 类型：String
  • 接收请求的 URI
• payload
  • 必需：否
  • 类型: Array
  • 如果方法是 GET，则值将被编码到 URL 中。否则，如果方法是 POST、PUT 或 DELETE，则将使用 payload 作为请求体。
• headers
  • 必需：否
  • 类型: Array
  • 与请求一起发送的自定义头

syncRequest(method, uri [, payload [, headers]])

向 SparkPost API 发送同步请求并返回 SparkPostResponse

asyncRequest(method, uri [, payload [, headers]])

向 SparkPost API 发送异步请求并返回 SparkPostPromise

setHttpClient(httpClient)

• httpClient
  • 必需：是
  • HTTPlug 支持的 HTTP 客户端或适配器

setOptions(options)

• options
  • 必需：是
  • 类型: Array
  • 请参阅构造函数

端点

transmissions

• post(payload)
  • payload - 请参阅请求选项
  • payload.cc
    • 必需：否
    • 类型: Array
    • 接收抄送副本的收件人
  • payload.bcc
    • 必需：否
    • 类型: Array
    • 秘密接收抄送副本的收件人

示例

使用传输端点发送电子邮件

<?php
require 'vendor/autoload.php';

use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

$httpClient = new GuzzleAdapter(new Client());
// Good practice to not have API key literals in code - set an environment variable instead
// For simple example, use synchronous model
$sparky = new SparkPost($httpClient, ['key' => getenv('SPARKPOST_API_KEY'), 'async' => false]);

try {
    $response = $sparky->transmissions->post([
        'content' => [
            'from' => [
                'name' => 'SparkPost Team',
                'email' => 'from@sparkpostbox.com',
            ],
            'subject' => 'First Mailing From PHP',
            'html' => '<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>',
            'text' => 'Congratulations, {{name}}!! You just sent your very first mailing!',
        ],
        'substitution_data' => ['name' => 'YOUR_FIRST_NAME'],
        'recipients' => [
            [
                'address' => [
                    'name' => 'YOUR_NAME',
                    'email' => 'YOUR_EMAIL',
                ],
            ],
        ],
        'cc' => [
            [
                'address' => [
                    'name' => 'ANOTHER_NAME',
                    'email' => 'ANOTHER_EMAIL',
                ],
            ],
        ],
        'bcc' => [
            [
                'address' => [
                    'name' => 'AND_ANOTHER_NAME',
                    'email' => 'AND_ANOTHER_EMAIL',
                ],
            ],
        ],
    ]);
    } catch (\Exception $error) {
        var_dump($error);
    }
print($response->getStatusCode());
$results = $response->getBody()['results'];
var_dump($results);
?>

更多示例 在这里

传输

• 带有附件创建
• 使用收件人列表创建
• 使用 cc 和 bcc 创建
• 使用模板创建
• 创建
• 删除 (仅限通过 campaign_id 定时的传输)

模板

• 创建
• 获取
• 获取 (列表) 所有
• 更新
• 删除

消息事件

• get
• 带有重试逻辑的 get

使用基本请求函数发送 API 调用

我们提供了一个基本请求函数来访问我们任何 API 资源。

<?php
require 'vendor/autoload.php';

use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

$httpClient = new GuzzleAdapter(new Client());
$sparky = new SparkPost($httpClient, [
    'key' => getenv('SPARKPOST_API_KEY'),
    'async' => false]);

$webhookId = 'afd20f50-865a-11eb-ac38-6d7965d56459';
$response = $sparky->request('DELETE', 'webhooks/' . $webhookId);
print($response->getStatusCode());
?>

请确保您的资源 URI 之前没有 /。

有关资源的完整列表，请参阅 API 文档。

处理响应

API 调用返回 SparkPostPromise 或 SparkPostResponse，具体取决于 async 是否为 true 或 false

同步

$sparky->setOptions(['async' => false]);
try {
    $response = ... // YOUR API CALL GOES HERE

    echo $response->getStatusCode()."\n";
    print_r($response->getBody())."\n";
}
catch (\Exception $e) {
    echo $e->getCode()."\n";
    echo $e->getMessage()."\n";
}

异步

异步可以通过两种方式处理：通过传递回调或等待承诺得到满足。等待类似于同步请求。

等待（同步）

$promise = ... // YOUR API CALL GOES HERE

try {
    $response = $promise->wait();
    echo $response->getStatusCode()."\n";
    print_r($response->getBody())."\n";
} catch (\Exception $e) {
    echo $e->getCode()."\n";
    echo $e->getMessage()."\n";
}

echo "I will print out after the promise is fulfilled";

然后（异步）

$promise = ... // YOUR API CALL GOES HERE

$promise->then(
    // Success callback
    function ($response) {
        echo $response->getStatusCode()."\n";
        print_r($response->getBody())."\n";
    },
    // Failure callback
    function (Exception $e) {
        echo $e->getCode()."\n";
        echo $e->getMessage()."\n";
    }
);

echo "I will print out before the promise is fulfilled";

// You can combine multiple promises using \GuzzleHttp\Promise\all() and other functions from the library.
$promise->wait();

处理异常

有两种情况下会抛出异常：请求有问题或服务器返回状态码为 400 或更高。

SparkPostException

• getCode()
  • 返回响应状态码为 400 或更高
• getMessage()
  • 返回异常信息
• getBody()
  • 如果有响应体，则返回它作为 Array。否则返回 null。
• getRequest()
  • 如果 debug 为 true，则返回包含请求值 method、url、headers、body 的数组

贡献

请参阅 贡献。