PHP, 什麼是?

MailChimp API v3 使用心得、教學

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

 

 

 

什麼是 MailChimp

mailchimp_logo
(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 : 可以自行製作訂閱表單, 幾乎沒有難度
mailchimp-Signup-forms

 

 

 

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
mailchimp-apikey
如上圖, 在 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

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

.

.

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

 

 

 

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 :

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

.

使用者訂閱狀態(status)

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

 

response :

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'
              ]);

 

response :

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

.

.

取消訂閱 (unsubscribed)

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

 

response :

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

.

.

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

 

 

己知問題 / 疑問

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

 

 

One Comment

發表迴響