mailjet/mailjet-apiv3-php-simple

此包已被废弃,不再维护。未建议替换包。

[API v3] Mailjet API 的简单 PHP 封装

v1.1.0 2015-10-14 09:24 UTC

README

首先阅读这个!!
此仓库现在被认为是过时的,不会再进行进一步开发。请参阅新版本

[API v3] Mailjet PHP 封装 v1.1.0

Build Status

目录

介绍

提供用于 MailJet API 最新版本的简单 PHP 库。此组件的目的是简化 PHP 开发人员对 MailJet API 的使用。

先决条件

请确保以下详细信息

  • Mailjet API 密钥
  • Mailjet API 密钥
  • PHP (版本 >= 5.3,最好是版本 >= 5.4)
  • 此 PHP 类

安装

首先克隆仓库

git clone https://github.com/mailjet/mailjet-apiv3-php-simple.git

进入 mailjet-apiv3-php-simple 文件夹并创建一个空文件,例如 myProjectEmailer.php

cd mailjet-apiv3-php-simple
touch myProjectEmailer.php

现在您可以开始使用了!

用法

在你的 myProjectEmailer.php 文件中,你需要包含我们的 PHP 类

include("php-mailjet-v3-simple.class.php");

注意:确保 myProjectEmailer.php 和 php-mailjet-v3-simple.class.php 文件位于同一文件夹中,以便包含操作能正常工作

现在你可以通过创建一个新的 Mailjet 对象并使用你的 API 密钥和密钥(可以在 https://app.mailjet.com/account/api_keys)开始使用 myProjectEmailer.php 文件

$mj = new Mailjet( $apiKey, $secretKey );

这基本上是启动引擎。接下来你要做什么取决于你想要通过 API 从 Mailjet 服务器获取、POST、PUT 或 DELETE 什么。访问 参考文档 了解所有可用的资源。

接下来,你将指定要调用哪种资源(例如,本例中的资源 Contact),并使用一个参数数组 $params

$mj->contact($params);

信息:如果你在数组 $params 中没有指定请求的方法(以下有示例),则默认为 GET。

示例

SendAPI

发送电子邮件的函数
function sendEmail()
{
    $mj = new Mailjet();
    $params = array(
        "method" => "POST",
        "from" => "ms.mailjet@example.com",
        "to" => "mr.mailjet@example.com",
        "subject" => "Hello World!",
        "text" => "Greetings from Mailjet."
    );

    $result = $mj->sendEmail($params);

    if ($mj->_response_code == 200)
       echo "success - email sent";
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
  • 注意。
    • 你可以发送作为副本的电子邮件("cc" => "email")和/或作为密件副本("bcc" => "email")。

    • 你可以通过在上述 $params 数组中使用数组向多个 "to""cc" 和/或 "bcc" 发送电子邮件

      "to" => array(
          "1foo@bar.foobar",
          "2foo@bar.foobar",
          ...
      ),
      "cc" => array(
          "3foo@bar.foobar",
          "4foo@bar.foobar",
          ...
      ),
      "bcc" => array(
          "5foo@bar.foobar",
          "6foo@bar.foobar",
          ...
      )
发送带有附件的电子邮件的函数(您的计算机上的绝对路径)
function sendEmailWithAttachments()
{
    $mj = new Mailjet();
    $params = array(
        "method" => "POST",
        "from" => "ms.mailjet@example.com",
        "to" => "mr.mailjet@example.com",
        "subject" => "Hello World!",
        "text" => "Greetings from Mailjet.",
        "attachment" => array(
            "MyFirstAttachment" => "@/path/to/first/file.txt",
            "@/path/to/second/file.pdf",
            "MyThirdAttachment" => "@/path/to/third/file.jpg"
            )
    );

    $result = $mj->sendEmail($params);

    if ($mj->_response_code == 200)
       echo "success - email sent";
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
  • 注意:关于附件,如上述代码所示,可以以两种不同的方式(但可以组合;PHP 真的很酷)声明它们
    • 使用 "key" => "value" 组合:其中 key 是文件名,而 value 是该文件的路径。这允许自定义文件名,而与实际文件独立。
    • 使用一个普通的包含要附加的文件路径的数组字段。该附件显示的名称将是文件的实际名称。
发送带有一些内联附件的电子邮件的函数(您的计算机上的绝对路径)
function sendEmailWithInlineAttachments()
{
    $mj = new Mailjet();
    $params = array(
        "method" => "POST",
        "from" => "ms.mailjet@example.com",
        "to" => "mr.mailjet@example.com",
        "subject" => "Hello World!",
        "html" => "<html>Greetings from Mailjet <img src=\"cid:MaPhoto\"><img src=\"cid:photo2.png\"></html>",
        "inlineattachment" => array(
            "MaPhoto" => "@/path/to/photo1.jpg",
            "@/path/to/photo2.png"
            )
    );

    $result = $mj->sendEmail($params);

    if ($mj->_response_code == 200)
       echo "success - email sent";
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
发送带有自定义 ID 的电子邮件的函数,如此处所述
function sendEmailWithCustomID()
{
    $mj = new Mailjet();

    $params = array(
        "method" => "POST",
        "from" => "ms.mailjet@example.com",
        "to" => "mr.mailjet@example.com",
        "subject" => "Hello World!",
        "text" => "Greetings from Mailjet.",
        "mj-customid" => "helloworld"
    );

    $result = $mj->sendEmail($params);

    if ($mj->_response_code == 200)
       echo "success - email sent";
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
发送带有事件负载的电子邮件的函数,如此处所述
function sendEmailWithEventPayload()
{
    $mj = new Mailjet();

    $params = array(
        "method" => "POST",
        "from" => "ms.mailjet@example.com",
        "to" => "mr.mailjet@example.com",
        "subject" => "Hello World!",
        "text" => "Greetings from Mailjet.",
        "mj-eventpayload" => '{"message": "helloworld"}'
    );

    $result = $mj->sendEmail($params);

    if ($mj->_response_code == 200)
       echo "success - email sent";
    else
       echo "error - ".$mj->_response_code;

    return $result;
}

账户设置

获取您的个人资料信息的函数
function viewProfileInfo()
{
    $mj = new Mailjet();
    $result = $mj->myprofile();

    if ($mj->_response_code == 200)
       echo "success - got profile information";
    else
       echo "error - ".$mj->_response_code;
}
更新您的个人资料中的 AddressCity 字段的函数
function updateProfileInfo()
{
    $mj = new Mailjet();
    $params = array(
        "method" => "PUT",
        "AddressCity" => "New York"
    );

    $result = $mj->myprofile($params);

    if ($mj->_response_code == 200)
       echo "success - field AddressCity changed";
    else
       echo "error - ".$mj->_response_code;

    return $result;
}

联系人 & 联系人列表

参考页面.

基本功能

打印联系人列表的功能
function listContacts()
{
    $mj = new Mailjet();
    $result = $mj->contact();

    if ($mj->_response_code == 200)
       echo "success - listed contacts";
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
使用数组更新具有ID $id的contactData资源的功能
function updateContactData($id)
{
    $mj = new Mailjet();
    $data = array(
        array(
            'Name' => 'lastname',
            'Value' => 'Jet'
        ),
        array(
            'Name' => 'firstname',
            'Value' => 'Mail'
        )
    );

    $params = array(
        'ID' => $id,
        'Data' => $data,
        'method' => 'PUT'
    );

    $result = $mj->contactdata($params);

    if ($mj->_response_code == 200)
       echo "success - data changed";
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
创建具有名称$Lname的列表的功能
function createList($Lname)
{
    $mj = new Mailjet();
    $params = array(
        "method" => "POST",
        "Name" => $Lname
    );

    $result = $mj->contactslist($params);

    if ($mj->_response_code == 201)
       echo "success - created list ".$Lname;
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
获取ID为$listID的列表的功能
function getList($listID)
{
    $mj = new Mailjet();
    $params = array(
        "method" => "VIEW",
        "ID" => $listID
    );

    $result = $mj->contactslist($params);

    if ($mj->_response_code == 200)
       echo "success - got list ".$listID;
    else
       echo "error - ".$mj->_response_code;

    return $result;
}

注意:您可以使用资源的唯一字段而不是ID,例如,在示例中的params数组中使用"unique" => "foo@bar.com"

创建具有电子邮件$Cemail的联系人功能
function createContact($Cemail)
{
    $mj = new Mailjet();
    $params = array(
        "method" => "POST",
        "Email" => $Cemail
    );

    $result = $mj->contact($params);

    if ($mj->_response_code == 201)
       echo "success - created contact ".$Cemail;
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
获取ID为$contactID的单个联系人的列表功能
/**
 *  @param int  $contactID  The ID of the contact
 */
function getContactsLists ($contactID)
{
    $mj = new Mailjet();
    $params = array(
        "ID"    =>  $contactID
    );
    $result = $mj->contactGetContactsLists($params);
    if ($mj->_response_code == 201)
       echo "success - fetched lists for contact ".$contactID;
    else
       echo "error - ".$mj->_response_code;
    return $result;
}
将ID为$contactID的联系人添加到ID为$listID的列表的功能

添加单个联系人到列表的首选方法将在下一项中描述。

function addContactToList($contactID, $listID)
{
    $mj = new Mailjet();
    $params = array(
        "method" => "POST",
        "ContactID" => $contactID,
        "ListID" => $listID,
        "IsActive" => "True"
    );

    $result = $mj->listrecipient($params);

    if ($mj->_response_code == 201)
       echo "success - contact ".$contactID." added to the list ".$listID;
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
$contact中描述的联系人添加到ID为$listID的列表的功能
/**
 *  @param  array   $contact    An array describing a contact.
 *                              Example below the function.
 *  @param  int     $listID     The ID of the list.
 *
 */
 function addDetailedContactToList ($contact, $listID)
 {
     $mj = new Mailjet(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
     $params = array(
         "method" => "POST",
         "ID" => $listID
     );
     $params = array_merge($params, $contact);
     $result = $mj->contactslistManageContact($params);
     if ($mj->_response_code == 201)
        echo "success - detailed contact ".$contactID." added to the list ".$listID;
     else
        echo "error - ".$mj->_response_code;
     return $result;
 }
 // $contact array example
 /*  $contact = array(
  *      "Email"         =>  "foo@bar.com",   // Mandatory field!
  *      "Name"          =>  "FooBar",
  *      "Action"        =>  "addnoforce",
  *      "Properties"    =>  array(
  *          "Prop1" =>  "value1",
  *          ...
  *      )
  *  );
  */

注意
action可以是addforceaddnoforceremoveunsub

将ID为$contactID的联系人添加、删除或退订到/从包含在$lists中的列表的功能
/**
 *  @param int      $contactID  The ID of the contact
 *  @param array    $lists      An array of arrays,
 *                              each one describing a list.
 *                              Example below the function.
 */
function addContactToLists ($contactID, $lists) {
    $mj = Mailjet('', '');
    $params = array(
        "method"        =>  "POST",
        "ID"            =>  $contactID,
        "ContactsLists"  =>  $lists
    );
    $result = $mj->contactManageContactsLists($params);
    if ($mj->_response_code == 204)
       echo "success - contact ".$contactID." added to the list(s)";
    else
       echo "error - ".$mj->_response_code;
    return $result;
}
// $lists array example
/*  $lists = array(
 *      array(
 *          "ListID"    =>  1,
 *          "Action"    =>  "remove"
 *      ),
 *      array(
 *          "ListID"    =>  4,
 *          "Action"    =>  "addnoforce"
 *      )
 *      // ...
 *  );
 */

注意
action可以是addforceaddnoforceremoveunsub

删除ID为$listID的列表的功能
function deleteList($listID)
{
    $mj = new Mailjet();
    $params = array(
        "method" => "DELETE",
        "ID" => $listID
    );

    $result = $mj->contactslist($params);

    if ($mj->_response_code == 204)
       echo "success - deleted list";
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
从ID为$listID的列表中获取退订的联系人功能
function getUnsubscribedContactsFromList($listID)
{
    $mj = new Mailjet();

    $params = array(
        "method" => "GET",
        "ContactsList" => $listID,
        "Unsub" => true
    );

    $result = $mj->listrecipient($params);

    if ($mj->_response_code == 200)
       echo "success - got unsubscribed contact(s) ";
    else
       echo "error - ".$mj->_response_code;

    return $result;
}
获取ID为$contactID的联系人功能
function getContact($contactID)
{
    $mj = new Mailjet();
    $params = array(
        "method" => "VIEW",
        "ID" => $contactID
    );

    $result = $mj->contact($params);

    if ($mj->_response_code == 200)
       echo "success - got contact ".$contactID;
    else
       echo "error - ".$mj->_response_code;

    return $result;
}

注意:您可以使用资源的唯一字段而不是ID,例如,在示例中的params数组中使用"unique" => "foo@bar.com"

异步作业

异步作业(简称async job)是一种在单个调用中添加或更新大量数据(例如联系人)的方法,该调用将返回一个用于检查作业进度的作业ID,该作业将通过另一个调用进行检查。

contact资源上执行异步作业

一个用于异步添加、删除或退订一个或多个列表中的联系人(s)的功能,并返回作业的状态数组
(适用于一次将大量联系人上传到一个或多个列表。)

本示例展示了如何从一个列表中删除指定的联系人并将他们添加到另一个列表(如果他们不在其中)。在 一个 调用中完成。

/**
 *  @param  array   $contacts   Should be an array of arrays,
 *                              each one describing a contact.
 *                              Example below the function.
 *
 *  @param  array   $lists      Should be an array of arrays,
 *                              each one describing a list.
 *                              Example below the function.
 */
function asyncTransferContactsToLists ($contacts, $lists)
{

    $mj = new Mailjet('', '');

    $params = array(
        "method"        =>  "POST",
        "ContactsLists" =>  $lists,
        "Contacts"      =>  $contacts
    );

    $asyncJobResponse = $mj->contactManageManyContacts($params);

    if ($mj->_response_code == 200)
        echo "success - proper request";
    else
        echo "error while accessing the resource - ".$mj->_response_code;

    return $asyncJobResponse;
}

// $contacts array example
/*  $contacts = array(
 *      array(
 *          "Email" =>  "foo@bar.org",
 *          ...
 *      ),
 *      array(
 *          "Email" =>  "foo2@bar.com",
 *          ...
 *      )
 *  );
 */

// $lists array example
/*  $lists = array(
 *      array(
 *          "ListID"    =>  1,
 *          "Action"    =>  "remove"
 *      ),
 *      array(
 *          "ListID"    =>  4,
 *          "Action"    =>  "addnoforce"
 *      )
 *  );
 */

注意
action可以是addforceaddnoforceremoveunsub

contactslist 资源上执行异步任务

一个函数,用于异步添加、删除或取消订阅联系人,并返回作业的状态数组

本示例展示了如何从联系人列表中取消订阅联系人。

/**
 *  @param  array   $contacts   Should be an array of arrays,
 *                              each one describing a contact.
 *                              Example below the function.
 *
 *  @param  int     $listID     The list ID.
 *
 */
function asyncManageContactsToList ($contacts, $listID)
{

    $mj = new Mailjet('', '');

    $params = array(
        "method"        =>  "POST",
        "Action"        =>  "unsub",
        "Contacts"      =>  $contacts
    );

    $asyncJobResponse = $mj->contactslistManageManyContacts($params);

    if ($mj->_response_code == 200)
        echo "success - proper request";
    else
        echo "error while accessing the resource - ".$mj->_response_code;

    return $asyncJobResponse;
}

// $contacts array example
/*  $contacts = array(
 *      array(
 *          "Email" =>  "foo@bar.org",
 *          ...
 *      ),
 *      array(
 *          "Email" =>  "foo2@bar.com",
 *          ...
 *      )
 *  );
 */

注意
action可以是addforceaddnoforceremoveunsub

监控异步作业

一个函数,用于获取先前启动的异步作业的状态

注意:这既适用于 contact 资源,也适用于 contactslist 资源。相应地调整下面的注释代码。

/**
 *  @param array $asyncJobResponse The result object returned by the async job. (See function above)
 *
 */
function getAsyncJobStatus ($asyncJobResponse)
{
    $mj = new Mailjet('', '');

    $jobID = $asyncJobResponse->Data[0]->JobID;

    $statusParams = array(
        "method"    =>  "VIEW",
        "ID"        =>  $jobID
    );

    $status = $mj->contactManageManyContacts($statusParams);
    // OR
    // $status = $mj->contactslistManageManyContacts($statusParams);

    if ($mj->_response_code == 200)
       echo "success - status obtained";
    else
       echo "error while retrieving the status - ".$mj->_response_code;

    return status;
}

从 CSV 文件中管理联系人列表中的联系人

"管理"在这里意味着 添加删除取消订阅

在某些情况下,您可能需要管理大量存储在 CSV 记录中的 contacts,这些记录与 contactslist 相关。以下是使用 PHP 包装器进行操作的步骤。

请注意,这些步骤代表一个单一的过程。不要单独执行每个步骤,而应作为一个整体执行。
您可以在这里找到示例脚本。

第零步:CSV 文件结构

CSV 文件的格式如下

"email","age"
"foo@example.org",42
"bar@example.com",13
"sam@ple.co.uk",37

请注意,CSV 文件中未定义的联系人属性将在第二步自动创建。

第一步:上传数据

第一步是将 CSV 数据上传到服务器。
您需要指定所需的 contactslist ID,当然还有 csv_content

$CSVContent = file_get_contents('test.csv');

$uploadParams = array(
    "method" => "POST",
    "ID" => $listID,
    "csv_content" => $CSVContent
);

$csvUpload = $mj->uploadCSVContactslistData($uploadParams);

if ($mj->_response_code == 200)
   echo "success - uploaded CSV file ";
else
   echo "error - ".$mj->_response_code;
第二步:管理联系人订阅到联系人列表

现在,您需要告诉 API 将上传的数据分配给给定的 contactslist 资源。

请注意,methodMethod 不是同一个字段。
Method 描述了联系人导入将如何执行。可能的值有 addforceaddnoforceremoveunsub

  • addforce 会添加联系人,并在必要时重新订阅到列表。
  • addnoforce 会添加联系人,但不会更改他们的订阅状态。
  • remove 会从列表中删除联系人。
  • unsub 会从列表中取消订阅联系人。
$assignParams = array(
    "method" => "POST",
    "ContactsListID" => $listID,
    "DataID" => $csvUpload->ID,
    "Method" => "addnoforce"
);

$csvAssign = $mj->csvimport($assignParams);

if ($mj->_response_code == 201)
   echo "success - CSV data ".$csvUpload->ID." assigned to contactslist ".$listID;
else
   echo "error - ".$mj->_response_code;
第三步:监控过程

剩下要做的就是确保任务成功完成,这可能需要多次检查,因为大量数据可能需要一些时间才能处理(几个小时并不罕见)。

$monitorParmas = array (
    "method" => "VIEW",
    "ID" => $csvAssign->Data[0]->ID
);

$res = $mj->batchjob($monitorParmas);

if ($mj->_response_code == 200)
   echo "job ".$res->Data[0]->Status."\n";
else
    echo "error - ".$mj->_response_code."\n";

新闻通讯

管理新闻通讯的内容

您可以使用 DetailContent 动作来管理通讯稿的内容,包括文本和 HTML。它有两个属性:Text-partHtml-part。您可以在该动作上使用 GETPOSTPUTDELETE 这四种请求。

  • GET:获取通讯稿的 Text-partHtml-part 属性。
  • POST:更新 Text-partHtml-part 的内容。如果您只指定其中一个,另一个将被清空。
  • PUT:更新 Text-partHtml-part 的内容。您可以只指定一个,它不会清空另一个。
  • DELETE:更新 Text-partHtml-part 的内容,并将两者都置为空。

以下是一个对 DetailContent 进行 GET 请求的示例

function getNewsletterDetailcontent($newsletter_id)
{
    $mj = new Mailjet('', '');
    $params = array(
        "method" => "GET",
        "ID" => $newsletter_id
    );

    $result = $mj->newsletterDetailContent($params);

    if ($mj->_response_code == 200)
        echo "success - got content for the newsletter ". $newsletter_id;
    else
        echo "error - ".$mj->_response_code;

    return $result;
}
安排通讯稿发送

使用 schedule 动作来安排通讯稿的发送时间。您只需执行一个 POST 请求来安排新的发送,并将 date 属性填充为 ISO 8601 格式的 Timestamp(时间戳)。请参考http://www.iso.org/iso/home/standards/iso8601.htm。您还可以在此处删除安排。以下是一个示例:

function scheduleNewsletter($newsletter_id)
{
    $mj = new Mailjet('', '');
    $params = array(
        "method" => "POST",
        "ID" => $newsletter_id,
        "date" => "2014-11-25T10:12:59Z"
    );

    $result = $mj->newsletterSchedule($params);

    if ($mj->_response_code == 201)
        echo "success - schedule done for the newsletter ". $newsletter_id;
    else
        echo "error - ".$mj->_response_code;

    return $result;
}
立即发送通讯稿

要立即发送通讯稿,您有两种可能性

  • POST 一个新的安排,其值设置为 NOW
  • 使用 send(仅支持 POST)对于第二种情况,以下是一个示例
function sendNewsletter($newsletter_id)
{
    $mj = new Mailjet('', '');
    $params = array(
        "method" => "POST",
        "ID" => $newsletter_id
    );

    $result = $mj->newsletterSend($params);

    if ($mj->_response_code == 201)
        echo "success - newsletter ". $newsletter_id . " has been sent";
    else
        echo "error - ".$mj->_response_code;

    return $result;
}
向测试收件人发送通讯稿

在执行实际发送之前,您还可以通过向一些指定的收件人发送通讯稿来测试通讯稿。为此,您需要对一个带有动作 test 的通讯稿执行一个 POST 请求,如下例所示

function testNewsletter($newsletter_id)
{
    $mj = new Mailjet('', '');
    $recipients = array(array('Email' => 'mailjet@example.org', 'Name' => 'Mailjet'));
    $params = array(
        "method" => "POST",
        "ID" => $newsletter_id,
        "Recipients" => $recipients
    );

    $result = $mj->newsletterTest($params);

    if ($mj->_response_code == 201)
        echo "success - newsletter ". $newsletter_id . " has been sent";
    else
        echo "error - ".$mj->_response_code;

    return $result;
}
复制现有的通讯稿

要复制现有的通讯稿,请使用 DuplicateFrom 过滤器,并指定要复制的通讯稿 ID。如果通讯稿是使用 API 或高级模式构建的,则 EditMode 设置为 html。如果您使用我们的 WYSIWYG 工具,则将其设置为 tool

function duplicateNewsletter($newsletter_id)
{
    $mj = new Mailjet('', '');
    $params = array(
        "method" => "POST",
        "EditMode" => "html",
        "Status" => 0,
        "_DuplicateFrom" => $newsletter_id
    );

    $result = $mj->newsletter($params);

    if ($mj->_response_code == 201)
        echo "success - duplicated Newsletter ". $newsletter_id;
    else
        echo "error - ".$mj->_response_code;

    return $result;
}

过滤

API 允许在 GETPOST 请求中对资源进行过滤。
但是,您需要根据您想要使用的过滤方法指定您想要使用的过滤器的不同方式。

对于 GET 请求

这很简单。只需将过滤器附加到参数数组中,就像附加一个额外参数一样。

需要显示 API 响应中 contactslist 中的前 10 个以外的 contacts 吗?请使用 limit 过滤器。

$params = array (
    "ContactsList"  =>  $contactslistID,
    "Limit" =>  "100"
);

$res = $mj->contacts($params);

对于 POST 请求

对于使用该方法的过滤器,包装器需要能够区分参数和过滤器。
如何?只需在过滤器的名称前附加一个 "_"(下划线字符)即可。

要复制通讯稿,请执行以下操作

$params = array(
        "method" => "POST",
        "EditMode" => "html",
        "Status" => 0,
        "_DuplicateFrom" => $newsletter_id
    );

$result = $mj->newsletter($params);

报告问题

在此处创建问题