MailChimp API v3 使用心得、教學

網路上似乎沒看見有關 MailChimp API v3 的使用說明、心得或教學
自已獻醜, 寫個簡單心得
>> 當有需要大量發佈 E-DM 時, 若是你沒有設計師, 沒有工程師, 那該怎麼辦呢?
使用 MailChimp 吧!
電子報大猩猩幫你處理電子報大小事!
Starting Up 免費方案, 宣稱永久免費, 並提供 2,000 訂閱人次, 每月 12,000 封 email

什麼是 MailChimp
API 使用前準備
API v3 心得、教學
已知問題 / 疑問

什麼是 MailChimp

(chimp : 大猩猩, 指一個聰明的服務, 幫你處理本來需要人類手動執行的繁瑣事務)

http://mailchimp.com/ 一個提供發佈電子報的線上服務平台
光是 Starting Up 免費方案, 宣稱永久免費, 並提供 2,000 訂閱人次, 每月 12,000 封 email

並且包含一些常見的好用功能 :

建立自已的訂閱清單
自訂屬於自己的訂閱表單
友善的電子報設計工具, 可以用拖拉的方式設計自已的電子報模板
匯入、匯出訂閱者名單
完善的報表系統, 包含 開信率、點擊率及使用者裝置等資訊..

其它方案 Pricing 方案 : http://mailchimp.com/pricing/

這麼好用的工具, 還不用嗎? 光是免費方案就很夠用了!
dcplus 數位行銷實戰家也為他寫過教學文章 : http://dcplus.com.tw/market/mailchimp

雖然在一般使用上的確不需要設計師、工程師, 不過今天要講的主題是 API
所以還是請你去生個一工程師出來吧 :p

PS : 可以自行製作訂閱表單, 幾乎沒有難度

API 使用前準備

你需要 :

一個工程師
MailChimp 帳號
API KEY
訂閱清單 ID (List ID)

工程師最好能有一個 MailChimp 的帳號, 請主帳號邀請你加入, 方便做一些 API 的觀察

在 MailChimp 管理介面 > Account > Settings > Users > Invite A User

可以設定的角色權限有 Owner, Admin, Manager, Author, Viewer, 依需求選擇吧!
(官方也很貼心的準備了, Invite 教學影片 http://kb.mailchimp.com/accounts/multi-user/manage-user-levels-in-your-account?&_ga=1.106099843.1671412754.1450177380)

接著取得 API key

MailChimp 管理介面 > Account > Settings > Extras > API keys

如上圖, 在 Your API keys 的位置點擊「Create A Key」, 就能取得 API Key 了

你的 API Key 可能會長得像這樣 : e2c2c2c2coi3sd5ai6fncc2c26-us12

取得訂閱清單 ID (List ID)

在管理頁面最上方 > Lists > 選擇目標 List (沒有的話就新建一個) > Settings > List name and campaign defaults > 畫面最右邊就有 List ID

(如上圖紅框、紅字處, 格式大概為 0c38383802)

官方在 2015-05-05 發佈了 v3 版本的 API, 而原來的 v2 不曉得何時會棄用, 所以建議使用 v3
官方的 API v3 文件 : http://mailchimp.com/api-v3/
你可以從官方提供的面板查目前 API 狀態 : http://developer.mailchimp.com/status/

** 在 MailChimp 管理介面 > Account > Settings > Extras > API keys 畫面的最下方, 有近期 24小時內的 API 使用情況
適合拿來 debug 用(如下圖)

API v3 心得、教學

就上面得到的 API Key : e2c2c2c2coi3sd5ai6fncc2c26-us12
使用時需要切割他, 由「–」切割為兩部份

e2c2c2c2coi3sd5ai6fncc2c26 = API Key 本體

us12 = endpoints, 即你被指派的伺服器

你的 API Url 為 : https://<dc>.api.mailchimp.com/3.0
其中的 <dc> 需要替換為 us12

因此你的 API Url 應該是…

https://us12.api.mailchimp.com/3.0

這麼做應該是為了分流, 當你在登入後台管理頁面時, 也會有一樣的情況
相關說明 : http://developer.mailchimp.com/documentation/mailchimp/guides/get-started-with-mailchimp-api-3/

PS : 當然你也可以選擇用 OAuth2 的方式透過 API 執行更多功能

我要的功能是 :

使用者訂閱狀態(status)
訂閱 (subscribed)
取消訂閱 (unsubscribed)
取得訂閱清單(List)成員 (members)

首先建立 curl 發射器, 粗略寫一下 PHP example Code
(用什麼語言都可以, curl 就行了)

$listId = 'f06b7e584c'; // 替換成你的 List ID

function test_api($method, $url_path = '', $data = []) {
    $url = 'https://<dc>.api.mailchimp.com/3.0';
    $apikey = 'e2c2c2c2coi3sd5ai6fncc2c26-us12'; // 替換成你的 API Key

    list(, $endpoints) = explode('-', $apikey);
    $url = str_replace('<dc>', $endpoints, $url); // api url: https://us12.api.mailchimp.com/3.0

    if($url_path) {
        $url .= '/' . $url_path;
    }

   //echo $url; // 拿掉該註解查看準備發出的 api url

   $jsonData = json_encode($data);

   $ch = curl_init();
   curl_setopt($ch, CURLOPT_URL, $url);
   curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
   curl_setopt($ch, CURLOPT_USERAGENT, 'VPS/MC-API:3.0');
   curl_setopt($ch, CURLOPT_TIMEOUT, 15);
   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
   curl_setopt($ch, CURLOPT_USERPWD, "user:" . $apikey);
   curl_setopt($ch, CURLOPT_CUSTOMREQUEST, strtoupper($method));
   curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
   $result = curl_exec($ch);
   curl_close($ch);

   return $result;
}

// 部份動作需要 hash e-mail
function mailToHash($email_address = null){
    return md5(strtolower($email_address));
}

先取得訂閱清單(List)成員 (members)

$result = test_api('GET', $url_path = 'lists/' . $listId . '/members');

response :
{“members”:[],”list_id”:”f06b7e584c”,”_links”:[{“rel”:”self”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c/members”,”method”:”GET”,”targetSchema”:”https://us12.api.mailchimp.com/schema/3.0/Lists/Members/Collection.json”,”schema”:”https://us12.api.mailchimp.com/schema/3.0/CollectionLinks/Lists/Members.json”},{“rel”:”parent”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c”,”method”:”GET”,”targetSchema”:”https://us12.api.mailchimp.com/schema/3.0/Lists/Instance.json”},{“rel”:”create”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c/members”,”method”:”POST”,”schema”:”https://us12.api.mailchimp.com/schema/3.0/Lists/Members/Instance.json”}],”total_items”:0}

回傳結果為 json, 可以看見 members 中沒有內容
.

使用者訂閱狀態(status)

$result = test_api('GET', $url_path = 'lists/' . $listId . '/members/' . mailToHash('[email protected]'));

response :
{“type”:”http://developer.mailchimp.com/documentation/mailchimp/guides/error-glossary/”,”title”:”Resource Not Found”,”status”:404,”detail”:”The requested resource could not be found.”,”instance”:””}

ps : 這裡需要裝 e-mail 做 hash

回傳結果中請看 status
404 表示查無該 e-mail, 表示該 e-mail 尚未訂閱該清單

已知的訂閱狀態 :

subscribed, 已訂閱
unsubscribed, 已退訂
pending, 尚未確認訂閱
cleaned, e-mail 被阻擋停用

官方文件 : http://developer.mailchimp.com/documentation/mailchimp/guides/manage-subscribers-with-the-mailchimp-api/

訂閱 (subscribed)

$r = test_api('POST', 
              $url_path = 'lists/' . $listId . '/members/', 
              [
                 'email_address' => '[email protected]',
                 'status' => 'pending'
              ]);

response :
{“id”:”1aedb8d9dc4751e229a335e371db8058″,”email_address”:”test@gmail.com”,”unique_email_id”:”f0917c7ee8″,”email_type”:”html”,”status”:”subscribed”,”merge_fields”:{“FNAME”:””,”LNAME”:””},”stats”:{“avg_open_rate”:0,”avg_click_rate”:0},”ip_signup”:””,”timestamp_signup”:””,”ip_opt”:”36.224.133.221″,”timestamp_opt”:”2015-12-31 07:23:17″,”member_rating”:2,”last_changed”:”2015-12-31 07:23:17″,”language”:””,”vip”:false,”email_client”:””,”location”:{“latitude”:0,”longitude”:0,”gmtoff”:0,”dstoff”:0,”country_code”:””,”timezone”:””},”list_id”:”f06b7e584c”,”_links”:[{“rel”:”self”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c/members/1aedb8d9dc4751e229a335e371db8058″,”method”:”GET”,”targetSchema”:”https://us12.api.mailchimp.com/schema/3.0/Lists/Members/Instance.json”},{“rel”:”parent”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c/members”,”method”:”GET”,”targetSchema”:”https://us12.api.mailchimp.com/schema/3.0/Lists/Members/Collection.json”,”schema”:”https://us12.api.mailchimp.com/schema/3.0/CollectionLinks/Lists/Members.json”},{“rel”:”update”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c/members/1aedb8d9dc4751e229a335e371db8058″,”method”:”PATCH”,”schema”:”https://us12.api.mailchimp.com/schema/3.0/Lists/Members/Instance.json”},{“rel”:”upsert”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c/members/1aedb8d9dc4751e229a335e371db8058″,”method”:”PUT”,”schema”:”https://us12.api.mailchimp.com/schema/3.0/Lists/Members/Instance.json”},{“rel”:”delete”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c/members/1aedb8d9dc4751e229a335e371db8058″,”method”:”DELETE”},{“rel”:”activity”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c/members/1aedb8d9dc4751e229a335e371db8058/activity”,”method”:”GET”,”targetSchema”:”https://us12.api.mailchimp.com/schema/3.0/Lists/Members/Activity/Collection.json”},{“rel”:”goals”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c/members/1aedb8d9dc4751e229a335e371db8058/goals”,”method”:”GET”,”targetSchema”:”https://us12.api.mailchimp.com/schema/3.0/Lists/Members/Goals/Collection.json”},{“rel”:”notes”,”href”:”https://us12.api.mailchimp.com/3.0/lists/f06b7e584c/members/1aedb8d9dc4751e229a335e371db8058/notes”,”method”:”GET”,”targetSchema”:”https://us12.api.mailchimp.com/schema/3.0/Lists/Members/Notes/Collection.json”}]}

在 POST Data 中指定兩個參數 :
email_address : 欲訂閱的 e-mail
status : pending 或 subscribed, subscribed 可直接讓使用者跳過訂閱確認信的動作

取消訂閱 (unsubscribed)

$result = test_api('DELETE', $url_path = 'lists/' . $listId . '/members/' . mailToHash('[email protected]'));

response :

取消訂閱的回傳是空的, 什麼都沒有!!
所以實做的時候請小心, 也可以在取消後再 members 或 status 再檢查一次

如果是配合 Framework 我個人是用社群上包裝好的 Package
https://github.com/vatps/mailchimp-rest-api
composer.json 在 require 中加入 “vatps/mailchimp-rest-api”: “dev-master”
再執行 composer update 就行了