MailChimp API v3 使用心得、教學

• 什麼是 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
使用時需要切割他, 由 「–」 切割為兩部份

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

因此你的 API Url 應該是…

這麼做應該是為了分流, 當你在登入後台管理頁面時, 也會有一樣的情況
相關說明 : 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');

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

.

使用者訂閱狀態(status)

$result = test_api('GET', $url_path = 'lists/' . $listId . '/members/' . mailToHash('test@gmail.com'));

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' => 'test@gmail.com',
                 'status' => 'pending'
              ]);

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

.

.

取消訂閱 (unsubscribed)

$result = test_api('DELETE', $url_path = 'lists/' . $listId . '/members/' . mailToHash('test@gmail.com')); 

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

.

.

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

己知問題 / 疑問

• 訂閱時, 沒有重發確認信的功能
  目前我的做法是, 直接幫使用者取消訂閱再重新訂閱, 藉此重發訂閱信
• 取消訂閱, 成功時沒有回傳值
  沒有回傳任何東西, 容易讓人誤會 API 是否失效