mailjet / mailjet-apiv3-php-simple
[API v3] Mailjet API 的简单 PHP 封装
Requires
- php: >=5.3.0
- dev-master
- v1.1.0
- v1.0.9
- v1.0.8
- v1.0.7
- 1.0.6
- 1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- dev-deprecated
- dev-dns
- dev-unescaped_slashes_polyfill
- dev-error
- dev-v2.0.0-fix
- dev-sendAPI_json
- dev-json_encode
- dev-data
- dev-108-merge
- dev-sboo-master
- dev-dev-contacts-actions
- dev-post-filters
- dev-custom-filename
- dev-csv_data
- dev-new-newsletter-endpoints
This package is not auto-updated.
Last update: 2020-01-24 15:24:00 UTC
README
首先阅读这个!! |
---|
此仓库现在被认为是过时的,不会再进行进一步开发。请参阅新版本。 |
[API v3] Mailjet PHP 封装 v1.1.0
目录
介绍
提供用于 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
可以是addforce
、addnoforce
、remove
或unsub
。
将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
可以是addforce
、addnoforce
、remove
或unsub
。
删除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
可以是addforce
、addnoforce
、remove
或unsub
。
在 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
可以是addforce
、addnoforce
、remove
或unsub
。
监控异步作业
一个函数,用于获取先前启动的异步作业的状态
注意:这既适用于 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
资源。
请注意,method 和 Method 不是同一个字段。
Method 描述了联系人导入将如何执行。可能的值有 addforce、addnoforce、remove 和 unsub。
- 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-part
和 Html-part
。您可以在该动作上使用 GET
、POST
、PUT
和 DELETE
这四种请求。
GET
:获取通讯稿的Text-part
和Html-part
属性。POST
:更新Text-part
和Html-part
的内容。如果您只指定其中一个,另一个将被清空。PUT
:更新Text-part
和Html-part
的内容。您可以只指定一个,它不会清空另一个。DELETE
:更新Text-part
和Html-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 允许在 GET
和 POST
请求中对资源进行过滤。
但是,您需要根据您想要使用的过滤方法指定您想要使用的过滤器的不同方式。
对于 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);
报告问题
在此处创建问题。