Categories: PHP什麼是?

MailChimp API v3 使用心得、教學

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

 

 

 

什麼是 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)

.

.

** 在 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 :

回傳結果為 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 是否失效

 

 

可樂

View Comments

Recent Posts

plain PHP 搭配 Slack 進行錯誤追蹤、回報(Error Tracking、Error Handling)

錯誤追蹤、回報非常重要,看到的錯誤才知道怎麼修。現今 PHP 流行的 Laravel 有很好的 Error Tracking, Error Handling。但 plain PHP 怎麼辦呢? 在 production 為了安全考量會設定…

4 years ago

Drone CI/CD 配合 Github 使用 Rsync 進行 Deploy

jenkins、circleci、travis 或 Gitlab CI 皆為目前暫知名的 CI/CD 服務,各自缺點也不言而喻...過於肥大、收費略高(?)、速度不夠快執問題...此時使用 go language 開發的 Drone 就出現啦,完全 docker 容器化的運行方式讓整個 CI…

4 years ago

Nginx brotli 設定

網頁壓縮技術中 gzip 很好用,deflate 己經過時,但你聽過 brotli 嗎? 有著比 gzip 更好、更快的壓縮效率。看起來利大於弊有什麼不用他的理由嗎?簡單從優、缺點來看 brotli!到底 brotli 布羅特利是什麼、如何設定呢。 目前大多的 web server…

4 years ago

本機使用 Docker 容器內 PHP (wrapper/expose PHP)

為什麼要讓本機使用 Docker 內 PHP? 情境... docker 容器內用的是 PHP 7.4 但你的開發本機還在跑 PHP 5.6 或是更舊,因為 dockerize 的關係會將所有相關環境都轉移到…

4 years ago

為什麼你需要密碼管理工具

為什麼你需要密碼管理工具現代人一天下來需要輸入多少組密碼,工作與生活己經和密碼密不可分! 除了足夠全安的密碼,密碼記錄、儲存的方式又足夠安全嗎?密碼管理工具可以帶來什麼幫助呢? 為什麼你需要密碼管理工具 資安問題!!大多人說著沒做壞事不怕被偷資料、監聽。嚴重曝露出現代人的基本科技素養的低落和無知 🤯 密碼的使用無所不在!! 行動裝置的普及,APP 、手機遊戲、銀行帳戶所有和生活相關的東西都需要密碼!!facebook, line 只要打開 APP 也會輸入密碼只是他是自動輸入、一般情況不可視 (auth token) 一般人最常發生的密碼資安問題…

4 years ago

簡單使用 Mysql Partition 優化查詢

mysql 資料表分區 mysql table partition 從架構上調整 mysql 的查詢效率。mysql DB 的優化可以簡單也能複雜,除了調整設定值。也可以透過水平分割(Horizontal Partitioning)、垂直分割(Vertical Partitioning) 分庫或分表將資料分散儲存減少資料搜尋、group by 時的效能消耗。拆開批次處理,理論上效率都會變好,本文就水平分割的…

4 years ago