使用 Mailchimp 的 API v3 将订阅者添加到列表
Posted
技术标签:
【中文标题】使用 Mailchimp 的 API v3 将订阅者添加到列表【英文标题】：Adding subscribers to a list using Mailchimp's API v3 【发布时间】：2015-08-09 12:15:01 【问题描述】：我正在尝试将用户添加到我在 Mailchimp 中创建的列表中，但我在任何地方都找不到任何代码示例。我已经尝试弄清楚如何使用 API，但我是一个非常喜欢“看例子然后学习”的人。
我已尝试使用 API 的第 2 版，但尽管从网上的示例开始工作，但似乎没有任何效果，Mailchimp 在其网站上对早期版本的 API 进行了以下说明：
2.0 及更早版本已弃用。这些版本仅提供最低限度的支持（错误修复、安全补丁）。
更新 1：我根据 TooMuchPete 的 answer 对管理订阅者的链接做了一些进一步的研究，并更改了我找到的一些代码 here，但它不起作用，因为函数http_build_query() 不处理嵌套数组。我不确定如何处理添加订阅者的“merge_fields”部分。我当前的代码如下：
$postdata = http_build_query(
array(
'apikey' => $apikey,
'email_address' => $email,
'status' => 'subscribed',
'merge_fields' => array(
'FNAME' => $name
)
)
);
$opts = array('http' =>
array(
'method' => 'POST',
'header' => 'Content-type: application/x-www-form-urlencoded',
'content' => $postdata
)
);
$context = stream_context_create($opts);
$result = file_get_contents('https://us2.api.mailchimp.com/3.0/lists/<list_id>/members/', false, $context);
var_dump($result);
die('Mailchimp executed');
更新 2：我现在求助于使用 curl 并且我已经设法得到了一些几乎可以工作的东西。数据发送到 Mailchimp，但我收到错误 “您的请求不包含 API 密钥。” 我猜我需要按照 @987654324 所述进行身份验证@。我已经尝试将它添加到没有工作的 http 标头中。请参阅下面的代码：
$apikey = '<api_key>';
$auth = base64_encode( 'user:'.$apikey );
$data = array(
'apikey' => $apikey,
'email_address' => $email,
'status' => 'subscribed',
'merge_fields' => array(
'FNAME' => $name
)
);
$json_data = json_encode($data);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://us2.api.mailchimp.com/3.0/lists/<list_id>/members/');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json/r/n
Authorization: Basic '.$auth));
curl_setopt($ch, CURLOPT_USERAGENT, 'php-MCAPI/2.0');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data);
$result = curl_exec($ch);
var_dump($result);
die('Mailchimp executed');
【问题讨论】：
v2.0 仍然可以正常工作。实际上，v1.3 也是如此——但如果您正在寻找 API v3.0 示例，我会查看 GitHub repo。它现在只有 Python，但这可能足以让你在你的语言中指出正确的方向。 managing subscribers 上的文档中还有一个页面，它与实际代码示例相距甚远，但可能仍然有帮助。 谢谢@TooMuchPete。我用代码示例更新了我的问题。我想我正在慢慢到达那里。 我正在寻找 Python 中的 API v3.0 示例，而不仅仅是基本的获取请求。 GitHub 存储库中的示例很糟糕，抱歉。 GET 请求和 POST 请求没有本质区别。一个有身体，一个没有。结合Python Requests 文档，我不确定其他人还需要什么才能开始。不过，这些示例绝对不适合寻找复制和粘贴解决方案或库的人。 MailChimp 目前表示他们不会支持 2016 年以后的 3.0 之前的版本。 【参考方案1】：基于List Members Instance docs，最简单的方法是使用 PUT 请求，根据文档，“添加新的列表成员或更新成员，如果电子邮件列表中已存在”。
此外，apikey 绝对不是json schema 的一部分，将其包含在您的 json 请求中是没有意义的。
此外，正如@TooMuchPete 的评论中所述，您可以使用CURLOPT_USERPWD 进行基本http 身份验证，如下所示。
我正在使用以下函数来添加和更新列表成员。您可能需要包含一组略有不同的merge_fields，具体取决于您的列表参数。
$data = [
'email' => 'johndoe@example.com',
'status' => 'subscribed',
'firstname' => 'john',
'lastname' => 'doe'
];
syncMailchimp($data);
function syncMailchimp($data)
$apiKey = 'your api key';
$listId = 'your list id';
$memberId = md5(strtolower($data['email']));
$dataCenter = substr($apiKey,strpos($apiKey,'-')+1);
$url = 'https://' . $dataCenter . '.api.mailchimp.com/3.0/lists/' . $listId . '/members/' . $memberId;
$json = json_encode([
'email_address' => $data['email'],
'status' => $data['status'], // "subscribed","unsubscribed","cleaned","pending"
'merge_fields' => [
'FNAME' => $data['firstname'],
'LNAME' => $data['lastname']
]
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, 'user:' . $apiKey);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
$result = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
return $httpCode;
【讨论】：
感谢@billynoah。我只是接受了我自己的答案，因为这是我设法得到的，没有其他人提供了一个有效的例子。 好吧，您仍然可以使用POST，但在不同的端点上（没有 ID）。来自 API 文档：Create a new record with either a POST request to /lists/list_id/members or a PUT request to /lists/list_id/members/id. Remove a record with a DELETE request to /lists/list_id/members/id.
@ToniMichelCaubet - 据我所知，文档没有提供任何方法来一次更新或添加多个成员。我认为您必须为每个要添加/编辑的成员发送一个请求。
如果您收到 404（找不到请求的资源），您可能使用了错误的列表 ID（请记住，它不是浏览器 url 中的 ID，而是包含字母和数字）。如果你得到一个 400，你应该检查你的数据数组。也许状态字段不包含字符串？
如果您不更改“johndoe”邮件，您也会收到 400 错误。【参考方案2】：
我让它工作了。我错误地将身份验证添加到标头：
$apikey = '<api_key>';
$auth = base64_encode( 'user:'.$apikey );
$data = array(
'apikey' => $apikey,
'email_address' => $email,
'status' => 'subscribed',
'merge_fields' => array(
'FNAME' => $name
)
);
$json_data = json_encode($data);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://us2.api.mailchimp.com/3.0/lists/<list_id>/members/');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
'Authorization: Basic '.$auth));
curl_setopt($ch, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data);
$result = curl_exec($ch);
var_dump($result);
die('Mailchimp executed');
【讨论】：
酷！您也可以像这样进行身份验证：url_setopt($ch, CURLOPT_USERPWD, "user:" . $apikey);
base64_encode 吗？ Mailchimp 要求对其进行编码。
MailChimp API v3.0 使用 HTTP 基本身份验证，这就是 cURLl 选项所做的。 Base64 编码只是基本身份验证的一部分。
我已经使用了提供的代码但仍然没有运气，我总是收到“找不到资源”错误。任何人都可以做到这一点？
如果有人无法让@VenomRush 代码按原样工作，则可能需要为您的帐户调整数据中心（由 CURLOPT_URL 行中的 us2 指示）。您可以通过查看 API 密钥的最后一部分来获取您帐户的数据中心。更多信息：developer.mailchimp.com/documentation/mailchimp/guides/…【参考方案3】：
这些都是很好的答案，但与如何获取表单来发送数据和处理该响应的完整答案无关。这将演示如何通过 jquery .ajax() 从 html 页面使用 API 的 v3.0 将成员添加到列表中。
在 Mailchimp 中：
-
获取您的API Key 和List ID
确保设置了列表以及要使用的自定义字段。在这种情况下，我在调用 API 之前已将
zipcode 设置为列表中的自定义字段。
查看API docs，了解将成员添加到列表。我们正在使用 create 方法，该方法需要使用 HTTP POST 请求。如果您希望能够修改/删除订阅，这里还有其他选项需要 PUT。
HTML：
<form id="pfb-signup-submission" method="post">
<div class="sign-up-group">
<input type="text" name="pfb-signup" id="pfb-signup-box-fname" class="pfb-signup-box" placeholder="First Name">
<input type="text" name="pfb-signup" id="pfb-signup-box-lname" class="pfb-signup-box" placeholder="Last Name">
<input type="email" name="pfb-signup" id="pfb-signup-box-email" class="pfb-signup-box" placeholder="youremail@example.com">
<input type="text" name="pfb-signup" id="pfb-signup-box-zip" class="pfb-signup-box" placeholder="Zip Code">
</div>
<input type="submit" class="submit-button" value="Sign-up" id="pfb-signup-button"></a>
<div id="pfb-signup-result"></div>
</form>
关键点：
-
为您的
<form> 提供一个唯一ID，不要忘记method="post" 属性，这样表单才能正常工作。
注意最后一行 #signup-result 是您存放 PHP 脚本反馈的地方。
PHP：
<?php
/*
* Add a 'member' to a 'list' via mailchimp API v3.x
* @ http://developer.mailchimp.com/documentation/mailchimp/reference/lists/members/#create-post_lists_list_id_members
*
* ================
* BACKGROUND
* Typical use case is that this code would get run by an .ajax() jQuery call or possibly a form action
* The live data you need will get transferred via the global $_POST variable
* That data must be put into an array with keys that match the mailchimp endpoints, check the above link for those
* You also need to include your API key and list ID for this to work.
* You'll just have to go get those and type them in here, see README.md
* ================
*/
// Set API Key and list ID to add a subscriber
$api_key = 'your-api-key-here';
$list_id = 'your-list-id-here';
/* ================
* DESTINATION URL
* Note: your API URL has a location subdomain at the front of the URL string
* It can vary depending on where you are in the world
* To determine yours, check the last 3 digits of your API key
* ================
*/
$url = 'https://us5.api.mailchimp.com/3.0/lists/' . $list_id . '/members/';
/* ================
* DATA SETUP
* Encode data into a format that the add subscriber mailchimp end point is looking for
* Must include 'email_address' and 'status'
* Statuses: pending = they get an email; subscribed = they don't get an email
* Custom fields go into the 'merge_fields' as another array
* More here: http://developer.mailchimp.com/documentation/mailchimp/reference/lists/members/#create-post_lists_list_id_members
* ================
*/
$pfb_data = array(
'email_address' => $_POST['emailname'],
'status' => 'pending',
'merge_fields' => array(
'FNAME' => $_POST['firstname'],
'LNAME' => $_POST['lastname'],
'ZIPCODE' => $_POST['zipcode']
),
);
// Encode the data
$encoded_pfb_data = json_encode($pfb_data);
// Setup cURL sequence
$ch = curl_init();
/* ================
* cURL OPTIONS
* The tricky one here is the _USERPWD - this is how you transfer the API key over
* _RETURNTRANSFER allows us to get the response into a variable which is nice
* This example just POSTs, we don't edit/modify - just a simple add to a list
* _POSTFIELDS does the heavy lifting
* _SSL_VERIFYPEER should probably be set but I didn't do it here
* ================
*/
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_USERPWD, 'user:' . $api_key);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $encoded_pfb_data);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$results = curl_exec($ch); // store response
$response = curl_getinfo($ch, CURLINFO_HTTP_CODE); // get HTTP CODE
$errors = curl_error($ch); // store errors
curl_close($ch);
// Returns info back to jQuery .ajax or just outputs onto the page
$results = array(
'results' => $result_info,
'response' => $response,
'errors' => $errors
);
// Sends data back to the page OR the ajax() in your JS
echo json_encode($results);
?>
关键点：
CURLOPT_USERPWD 处理 API 密钥，而 Mailchimp 并没有真正向您展示如何执行此操作。
CURLOPT_RETURNTRANSFER 以这样一种方式向我们提供响应，以便我们可以使用 .ajax() success 处理程序将其发送回 HTML 页面。
在收到的数据上使用json_encode。
JS：
// Signup form submission
$('#pfb-signup-submission').submit(function(event)
event.preventDefault();
// Get data from form and store it
var pfbSignupFNAME = $('#pfb-signup-box-fname').val();
var pfbSignupLNAME = $('#pfb-signup-box-lname').val();
var pfbSignupEMAIL = $('#pfb-signup-box-email').val();
var pfbSignupZIP = $('#pfb-signup-box-zip').val();
// Create JSON variable of retreived data
var pfbSignupData =
'firstname': pfbSignupFNAME,
'lastname': pfbSignupLNAME,
'email': pfbSignupEMAIL,
'zipcode': pfbSignupZIP
;
// Send data to PHP script via .ajax() of jQuery
$.ajax(
type: 'POST',
dataType: 'json',
url: 'mailchimp-signup.php',
data: pfbSignupData,
success: function (results)
$('#pfb-signup-box-fname').hide();
$('#pfb-signup-box-lname').hide();
$('#pfb-signup-box-email').hide();
$('#pfb-signup-box-zip').hide();
$('#pfb-signup-result').text('Thanks for adding yourself to the email list. We will be in touch.');
console.log(results);
,
error: function (results)
$('#pfb-signup-result').html('<p>Sorry but we were unable to add you into the email list.</p>');
console.log(results);
);
);
关键点：
JSON 数据在传输时非常敏感。在这里，我将它放入一个数组中，看起来很简单。如果您遇到问题，很可能是因为您的 JSON 数据的结构。看看这个！
JSON 数据的键将成为您在 PHP _POST 全局变量中引用的键。在这种情况下，它将是_POST['email']、_POST['firstname'] 等。但是您可以为它们命名任何您想要的名称 - 只需记住您为 JSON 传输的 data 部分的键命名的名称就是您在 PHP 中访问它们的方式。
这显然需要 jQuery ;)
【讨论】：
您好，伙计，我按照您的代码示例进行操作，但无法使其适用于我的项目。你介意我们联系一下，以便我从你那里得到一些帮助吗？谢谢！ 提出一个要点，我会检查一下。【参考方案4】：批量加载 - 好的，所以在删除了我之前的回复后，我只使用了链接，我已经更新了我设法开始工作的代码。感谢任何人简化/纠正/改进/添加功能等，因为我仍在学习这些东西，但我得到了批处理成员列表添加工作:)
$apikey = "whatever-us99";
$list_id = "12ab34dc56";
$email1 = "jack@email.com";
$fname1 = "Jack";
$lname1 = "Black";
$email2 = "jill@email.com";
$fname2 = "Jill";
$lname2 = "Hill";
$auth = base64_encode( 'user:'.$apikey );
$data1 = array(
"apikey" => $apikey,
"email_address" => $email1,
"status" => "subscribed",
"merge_fields" => array(
'FNAME' => $fname1,
'LNAME' => $lname1,
)
);
$data2 = array(
"apikey" => $apikey,
"email_address" => $email2,
"status" => "subscribed",
"merge_fields" => array(
'FNAME' => $fname2,
'LNAME' => $lname2,
)
);
$json_data1 = json_encode($data1);
$json_data2 = json_encode($data2);
$array = array(
"operations" => array(
array(
"method" => "POST",
"path" => "/lists/$list_id/members/",
"body" => $json_data1
),
array(
"method" => "POST",
"path" => "/lists/$list_id/members/",
"body" => $json_data2
)
)
);
$json_post = json_encode($array);
$ch = curl_init();
$curlopt_url = "https://us99.api.mailchimp.com/3.0/batches";
curl_setopt($ch, CURLOPT_URL, $curlopt_url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
'Authorization: Basic '.$auth));
curl_setopt($ch, CURLOPT_USERAGENT, 'PHP-MCAPI/3.0');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_post);
print_r($json_post . "\n");
$result = curl_exec($ch);
var_dump($result . "\n");
print_r ($result . "\n");
【讨论】：
【参考方案5】：如果它对任何人有帮助，这就是我在 Python 中使用 Python Requests 库而不是 CURL 所做的工作。
正如上面@staypuftman 所解释的，您需要来自 MailChimp 的 API 密钥和列表 ID，并确保您的 API 密钥后缀和 URL 前缀（即 us5）匹配。
Python：
#########################################################################################
# To add a single contact to MailChimp (using MailChimp v3.0 API), requires:
# + MailChimp API Key
# + MailChimp List Id for specific list
# + MailChimp API URL for adding a single new contact
#
# Note: the API URL has a 3/4 character location subdomain at the front of the URL string.
# It can vary depending on where you are in the world. To determine yours, check the last
# 3/4 characters of your API key. The API URL location subdomain must match API Key
# suffix e.g. us5, us13, us19 etc. but in this example, us5.
# (suggest you put the following 3 values in 'settings' or 'secrets' file)
#########################################################################################
MAILCHIMP_API_KEY = 'your-api-key-here-us5'
MAILCHIMP_LIST_ID = 'your-list-id-here'
MAILCHIMP_ADD_CONTACT_TO_LIST_URL = 'https://us5.api.mailchimp.com/3.0/lists/' + MAILCHIMP_LIST_ID + '/members/'
# Create new contact data and convert into JSON as this is what MailChimp expects in the API
# I've hardcoded some test data but use what you get from your form as appropriate
new_contact_data_dict =
"email_address": "test@testing.com", # 'email_address' is a mandatory field
"status": "subscribed", # 'status' is a mandatory field
"merge_fields": # 'merge_fields' are optional:
"FNAME": "John",
"LNAME": "Smith"
new_contact_data_json = json.dumps(new_contact_data_dict)
# Create the new contact using MailChimp API using Python 'Requests' library
req = requests.post(
MAILCHIMP_ADD_CONTACT_TO_LIST_URL,
data=new_contact_data_json,
auth=('user', MAILCHIMP_API_KEY),
headers="content-type": "application/json"
)
# debug info if required - .text and .json also list the 'merge_fields' names for use in contact JSON above
# print req.status_code
# print req.text
# print req.json()
if req.status_code == 200:
# success - do anything you need to do
else:
# fail - do anything you need to do - but here is a useful debug message
mailchimp_fail = 'MailChimp call failed calling this URL: 0\n' \
'Returned this HTTP status code: 1\n' \
'Returned this response text: 2' \
.format(req.url, str(req.status_code), req.text)
【讨论】：
【参考方案6】：如果您想使用 Mailchimp API 在列表上批量订阅。然后就可以使用下面的函数了。
/**
* Mailchimp API- List Batch Subscribe added function
*
* @param array $data Passed you data as an array format.
* @param string $apikey your mailchimp api key.
*
* @return mixed
*/
function batchSubscribe(array $data, $apikey)
$auth = base64_encode('user:' . $apikey);
$json_postData = json_encode($data);
$ch = curl_init();
$dataCenter = substr($apikey, strpos($apikey, '-') + 1);
$curlopt_url = 'https://' . $dataCenter . '.api.mailchimp.com/3.0/batches/';
curl_setopt($ch, CURLOPT_URL, $curlopt_url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
'Authorization: Basic ' . $auth));
curl_setopt($ch, CURLOPT_USERAGENT, 'PHP-MCAPI/3.0');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_postData);
$result = curl_exec($ch);
return $result;
批量操作的函数使用和数据格式：
<?php
$apikey = 'Your MailChimp Api Key';
$list_id = 'Your list ID';
$servername = 'localhost';
$username = 'Youre DB username';
$password = 'Your DB password';
$dbname = 'Your DB Name';
// Create connection
$conn = new mysqli($servername, $username, $password, $dbname);
// Check connection
if ($conn->connect_error)
die('Connection failed: ' . $conn->connect_error);
$sql = 'SELECT * FROM emails';// your SQL Query goes here
$result = $conn->query($sql);
$finalData = [];
if ($result->num_rows > 0)
// output data of each row
while ($row = $result->fetch_assoc())
$individulData = array(
'apikey' => $apikey,
'email_address' => $row['email'],
'status' => 'subscribed',
'merge_fields' => array(
'FNAME' => 'eastwest',
'LNAME' => 'rehab',
)
);
$json_individulData = json_encode($individulData);
$finalData['operations'][] =
array(
"method" => "POST",
"path" => "/lists/$list_id/members/",
"body" => $json_individulData
);
$api_response = batchSubscribe($finalData, $apikey);
print_r($api_response);
$conn->close();
另外，您可以在我的 Github gist 中找到此代码。 GithubGist Link
参考文档：Official
【讨论】：
以上是关于使用 Mailchimp 的 API v3 将订阅者添加到列表的主要内容，如果未能解决你的问题，请参考以下文章
使用 cURL 和 Mailchimp API v3 更新列表中的订阅者
使用 MailChimp API v3.0 创建新的订阅者验证错误
Mailchimp API v3.0“status”：“subscribed”总是导致“status”：“pending”
Mailchimp API V3 jQuery Ajax POST 订阅者