sendwithus/api

本包最新版本（v6.4.0）没有可用的许可证信息。

sendwithus.com PHP客户端

维护者

详细信息

github.com/sendwithus/sendwithus_php

源代码

问题

安装: 669 686

依赖项: 2

建议者: 0

安全性: 0

星标: 20

关注者: 26

分支: 19

公开问题: 1

v6.4.0 2022-07-13 23:10 UTC

Requires (Dev)

Unknown License 8c27acf21bc15a79f54ab4e5fb200988a4e85dc9

This package is not auto-updated.

Last update: 2024-09-14 15:18:07 UTC

README

Sendwithus PHP客户端

状态

Build Status

需求

curl library must be installed and enabled in php.ini

通过Composer安装它

将其添加到您的composer.json文件中

{
    "require": {
        "sendwithus/api": "^6.4"
    }
}

然后使用以下命令安装它

composer install

入门

// Yii Users
Yii::$classMap = array(
    'sendwithus\\API' => dirname($_SERVER['DOCUMENT_ROOT']) . '/path/to/sendwithus/lib/API.php'
);

// composer users
use sendwithus\API;

require_once 'vendor/autoload.php';


$API_KEY = 'THIS_IS_A_TEST_API_KEY';
$options = array(
    'DEBUG' => true,
    'API_DEBUG_HANDLER' => function ($message, $priority_level) {
        // possible priority levels - https://php.ac.cn/manual/en/function.syslog.php
        error_log("[SendWithUs][$priority_level] " . $message);
    }
);

$api = new API($API_KEY, $options);

电子邮件

获取电子邮件

$response = $api->emails();

获取特定模板

$response = $api->get_template($template_id,     //string id of template
                               $version_id       //optional string version id of template
);

创建电子邮件

创建新电子邮件

我们验证所有HTML内容

$response = $api->create_email('Email Name',               // string email name
    'Email Subject',                                       // string subject line of email
    '<html><head></head><body>Valid HTML<body></html>',    // string of HTML code for email
    'Optional text content')                               // optional string of text for email

创建新电子邮件模板版本

我们验证所有HTML内容

$response = $api->create_new_template_version(
    'Email Name',                                          // string email version name
    'Email Subject',                                       // string subject of email
	'tem_JAksjdjwJXUVwnemljflksEJks',                      // string id of email used
    '<html><head></head><body>Valid HTML<body></html>',    // string block of HTML code used for email
    'Optional text content')                               // optional string of text used for email

更新电子邮件版本

我们验证所有HTML内容

$response = $api->update_template_version(
    'Email Name',                                          // string email version name
    'Email Subject',                                       // string subject of email
	'tem_JAkCjdjwJXUVwnemljflksEJks',                      // string id of email being updated
	'ver_iuweJskj4Jwkj2ndclk4jJDken',                      // string version of email being updated
    '<html><head></head><body>Valid HTML<body></html>',    // string block of HTML code used for email
    'Optional text content')                               // optional string of text used for email

发送电子邮件

注意 - 如果指定的电子邮件（收件人地址）不存在，发送调用将创建一个客户。

// Send function header
send(
    $email_id,      // string, id of email to send (template id)
    $recipient,     // associative array, ("address" => "ckent@dailyplanet.com", "name" => "Clark") to send to
    $args           // (optional) array, (array) additional parameters - (see below)
)

// Send function options
'template_data'  // array of variables to merge into the template.
'sender'         // array ("address", "name", "reply_to") of sender.
'cc'             // array of ("address", "name") for carbon copy.
'bcc'            // array of ("address", "name") for blind carbon copy.
'inline'         // string, path to file to include inline
                 // or an associative array with "id" containing filename
                 // and "data" containing base64 encoded file content
'files'          // array, each element represents either a string path to file to attach
                 // or an associative array with "id" containing filename
                 // and "data" containing base64 encoded file content
'tags'           // array of strings to tag email send with.
'esp_account'    // string of ESP ID to manually select ESP
'headers'        // associative array of header name and value

发送示例

只发送带有必需参数的请求

$response = $api->send('email_id',
    array('address' => 'us@sendwithus.com')
);

发送带有必需和可选参数的请求

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'),
    array(
    	'template_data' => array('name' => 'Jimmy the snake'),
    	'sender' => array(
            'name' => 'Company',
            'address' => 'company@company.com',
            'reply_to' => 'info@company.com'
        ),
        'esp_account' => 'esp_EMpi5eo59cG4cCWd7AdW7J'
    )
);

发送带有多个CC/BCC收件人的电子邮件

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'
    ),
    array(
        'template_data' => array('name' => 'Jimmy the snake'),
        'sender' => array(
            'name' => 'Company',
            'address' => 'company@company.com',
            'reply_to' => 'info@company.com'
        ),
        'cc' => array(
            array(
                'name' => 'CC Name',
                'address' => 'CC@company.com'
            ),
            array(
                'name' => 'CC 2 Name',
                'address' => 'CC2@company.com'
            )
        ),
        'bcc' => array(
            array(
                'name' => 'BCC Name',
                'address' => 'BCC@company.com'
            )
        )
    )
);

发送带有动态标签的电子邮件

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'),
    array(
        'tags' => array('Production', 'Client1')
    )
);

发送特定版本的电子邮件

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'),
    array(
        'version_name' => 'My Version'
    )
);

发送带有内联图像附件的电子邮件

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'),
    array(
        'inline' => 'filename.jpg'
    )
);

发送带有内联编码图像附件的电子邮件

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'),
    array(
        'inline' => array(
            'id' => 'photo.jpg',
            'data' => base64_encode(file_get_contents('filename.jpg'))
        )
    )
);

发送带有附件的电子邮件

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'),
    array(
        'files' => array(
            'filename.txt',
            'filename.pdf',
            array(
                'id' => 'photo.jpg',
                'data' => base64_encode(file_get_contents('filename.jpg'))
            )
        )
    )
);

渲染模板

// Render function header
render(
    $email_id,      // string, id of email to send (template id)
    $args           // (optional) array, (array) additional parameters - (see below)
)

// Send function options
'template_data'  // Array of variables to merge into the template.
'version_id'     // Version ID obtained from /templates/(:template_id)/versions
'version_name'   // Version name that you want rendered (provide either a version_name or a version_id, not both)
'locale'         // Template locale to render
'strict'         // Render in strict mode (fails on missing template data)

示例

$response = $api->render('email_id',
    array('address' => 'us@sendwithus.com'),
    array(
        'template_data' => array(
            'name' => 'Bobby Boucher'
        )
    )
);

获取特定电子邮件的日志

get_log(
    $log_id          // id of log to retrieve
)

示例

$response = api->get_log('log_d4R7hV4d0r')

响应

(
    [email_id] => tem_1jeid84bg
    [recipient_name] =>
    [message] => Mandrill: Message has been successfully delivered to the receiving server.
    [id] => log_d4R7hV4d0r
    [object] => log
    [created] => 1409287597
    [email_name] => test
    [recipient_address] => person@example.com
    [status] => sent
    [email_version] => Original Version
)

从日志中重发特定电子邮件

resend(
    $log_id          // id of log to resend
)

示例

$response = api->resend('log_d4R7hV4d0r')

响应

(
    [status] => OK
    [receipt_id] => 130be975-dc07-4071-9333-58530e5df052-i03a5q
    [email] => stdClass Object
        (
            [locale] => en-US
            [version_name] => Test Template
            [name] => test
        )

    [success] => 1
)

滴灌退订

// Unsubscribe email address from active drips
drip_unsubscribe(
    $email_address,      // the email to unsubscribe from active drips
)

滴灌退订示例

$response = $api->drip_unsubscribe('us@sendwithus.com');

滴灌2.0

列出滴灌活动

列出当前配置文件的所有滴灌活动

示例

$response = $api->list_drip_campaigns();

响应

Array
(
    [0] => stdClass Object
        (
            [drip_steps] => Array
                (
                    [0] => stdClass Object
                        (
                            [id] => dcs_1234abcd1234
                            [object] => drip_step
                            [delay_seconds] => 0
                            [email_id] => tem_1234abcd1234
                        )

                )

            [name] => Drip Campaign
            [enabled] => 1
            [id] => dc_1234abcd1234
            [trigger_email_id] => tem_1234abcd1234
            [object] => drip_campaign
        )
)

开始滴灌活动

将客户开始于指定滴灌活动的第一步

start_on_drip_campaign(
    $recipient_address, // string, email address being added to drip campaign
    $drip_campaign_id,  // string, drip campaign being added to
    $data               // array, (optional) email data being added to drip campaign
    $args               // array, (optional) additional options being sent with email (tags, cc's, etc)
);

// Args options
'sender'      // array ("address", "name", "reply_to") of sender.
'cc'          // array of ("address", "name") for carbon copy.
'bcc'         // array of ("address", "name") for blind carbon copy.
'tags'        // array of strings to tag email send with.
'esp_account' // string of ESP ID to manually select ESP

示例

$template_data = array(
    'name' => 'Jean-Luc',
    'rank' => 'Captain'
);

$args = array(
    'tags' => array('all', 'the', 'tags'),
    'cc' => array('address' => 'them@sendwithus.com')
);
$response = $api->start_on_drip_campaign('us@sendwithus.com', 'dc_1234abcd1234', $template_data, $args);

响应

stdClass Object
(
    [success] => 1
    [drip_campaign] => stdClass Object
        (
            [id] => dc_1234abcd1234
            [name] => Drip Campaign
        )

    [message] => Recipient successfully added to drip campaign.
    [status] => OK
    [recipient_address] => us@sendwithus.com
)

从滴灌活动中移除

停用指定滴灌活动中客户的所有待发送电子邮件

$response = $api->remove_from_drip_campaign(
    $recipient_address, // string, email address being removed from drip campaign
    $drip_campaign_id   // string, drip campaign being removed from
);

示例

$response = $api->remove_from_drip_campaign('us@sendwithus.com', 'dc_1234abcd1234');

响应

stdClass Object
(
    [success] => 1
    [drip_campaign] => stdClass Object
        (
            [id] => dc_1234abcd1234
            [name] => Drip Campaign
        )

    [message] => Recipient successfully removed from drip campaign.
    [status] => OK
    [recipient_address] => us@sendwithus.com
)

列出滴灌活动详细信息

显示指定活动中的所有步骤和其他信息

$response = $api->drip_campaign_details(
    $drip_campaign_id   // string, drip campaign to list details from
);

示例

$response = $api->drip_campaign_details('dc_1234abcd1234');

响应

stdClass Object
(
    [drip_steps] => Array
        (
            [0] => stdClass Object
                (
                    [id] => dcs_1234abcd1234
                    [object] => drip_step
                    [delay_seconds] => 0
                    [email_id] => tem_1234abcd1234
                )

        )

    [name] => Drip Campaign
    [enabled] => 1
    [id] => dc_1234abcd1234
    [trigger_email_id] => tem_1234abcd1234
    [object] => drip_campaign
)

客户API

创建客户

create_customer(
    $email,             // string, email of customer
    $data,              // array, optional, data for customer
    $args               // array, optional, optional parameters:

    // The additional optional parameters are as follows:
    //      'locale' - Default is null. String to specify a locale for this customer.
)

示例

$response = $api->create_customer('us@sendwithus.com',
    array('name' => 'Sendwithus')
);

更新客户

update_customer(
    $email,             // string, email of customer
    $data,              // array, optional, data for customer
)

示例

$response = $api->update_customer('us@sendwithus.com',
    array('name' => 'Sendwithus.com')
);

删除客户

delete_customer(
    $email,             // string, email of customer
)

示例

$response = $api->delete_customer('us@sendwithus.com');

列出客户日志

列出所有客户日志

示例

$response = api->get_customer_logs("email@email.com");

print_r($response);

/*
(
    [success] => 1
    [logs] => Array
        (
        [email_name] => Name of email
        [message] => Message body
        [recipient_name] => Recipient name
        [email_version] => Name of email version
        [object] => log
        [email_id] => ID of email
        [created] => Time stamp
        [recipient_address] => Email address of recipient
        [status] => Status of email
        [id] => ID of log
        )
    [status] => OK
)
*/

批量API

将请求组合在一起一次性运行。

用法

通过调用start_batch()创建一个batch_api对象。

像通常使用API一样，在batch_api对象上执行任何请求。

通过在对象上调用execute()一次性执行所有命令。

示例

$batch_api = api->start_batch();
for($i = 0; $i < 10; $i++) {
    $result = $batch_api->create_customer('us@sendwithus.com',
        array('name' => 'Sendwithus'));
    // $result->success == true && $result->status == 'Batched'
}
$result = $batch_api->execute();

// $result will be an array of responses for each command executed.

取消批量请求

有时需要取消所有已批处理但尚未发送的API请求。为此，请使用cancel()

示例

$batch_api = api->start_batch();
for($i = 0; $i < 10; $i++) {
    $batch_api->create_customer('us@sendwithus.com',
        array('name' => 'Sendwithus'));
}
$result = $batch_api->cancel();
// $result->success == true && $result->status == 'Canceled'

一旦取消了批量，您就可以继续使用批量来发送更多请求。

测试

运行单元测试

请确保已安装phpunit（http://phpunit.de/）并从根目录运行以下命令

phpunit test

故障排除

一般故障排除

  • 启用调试模式
  • 确保您正在使用最新的PHP客户端
  • 确保包含data/ca-certificate.pem。此文件是必需的
  • 捕获响应数据并检查您的日志 - 通常这将包含确切的错误

启用调试模式

调试模式会打印出底层cURL信息和发送到Sendwithus的数据有效负载。您很可能会在日志中找到这些信息。要启用它，只需在实例化API对象时在可选参数中放置"DEBUG" => true即可。使用调试模式来比较发送到sendwithus的API文档的数据有效负载。

$API_KEY = 'THIS_IS_AN_EXAMPLE_API_KEY';
$options = array(
    'DEBUG' => true
);

$api = new API($API_KEY, $options);

响应范围

Sendwithus的API通常在这些范围内发送响应

  • 2xx – 成功请求
  • 4xx – 请求失败（客户端错误）
  • 5xx – 请求失败（服务器错误）

如果您在400响应范围内收到错误，请按照以下步骤操作

  • 请仔细检查传递给Sendwithus的数据和ID
  • 确保您的API密钥正确无误
  • 请确保传递的ID中没有多余的空格

注意：启用调试模式以检查响应代码。