Мы тестируем API запросы в Mailchimp заранее, чтобы успешно интегрировать платформу с сайтом.
API запросы нужны в email-маркетинге для того, чтобы передавать данные с сайта в платформу рассылок. Это может быть передача подписчиков в список, добавление им тегов, изменение значений дополнительных полей, отправка триггерных писем из платформы по запросу.
В сложных email-маркетинговых платформах всё строится на подобных запросах. Но даже в небольших проектах порой не хватает базовых интеграций, которые предлагает платформа, и нужно составлять кастомные API запросы.
Эта статья будет полезна для email-маркетологов, поможет им разобраться, как построить API запросы в Mailchimp и передать их в настройку для backend-разработчика. На сайте запрос настраивается в PHP — пример таких запросов мы тоже будем приводить, но более подробно разберём запросы, которые будет использовать маркетолог.
В теории email-маркетолог должен прочитать справку по API от Mailchimp и на её основе строить запросы и готовить ТЗ для запросов. На практике это может отнимать много времени и сил.
Разберу примеры API запросов в Mailchimp, которые можно будет протестировать. Можно брать примеры этих запросов, менять данные под свой проект и тестировать.
Далее мы для каждого примера составим URL запроса, тело запроса и протестируем работу в Postman. А для некоторых — добавим пример запроса для PHP, который может потребоваться разработчику.
Вот из чего состоит интерфейс программы.
Здесь пишем URL запроса и метод. Чаще всего используются два метода запроса:
Для доступа к платформе при выполнении некоторых запросов нужна авторизация. Обязательность её зависит от платформы, с которой вы работаете и от её API.
Например, при тестировании запросов в ExpertSender авторизация не нужна: все необходимые данные уже есть в запросе. Если мы работаем с API от Toggl, то должны авторизоваться Toggl-аккаунт. А вот для Mailchimp нужно использовать Basic Auth, где в качестве пароля будет использоваться индивидуальный идентификатор API key. Таким образом, во вкладке Username вы вводите свой логин или почту, а во вкладке Password — свой API key.
Возможно, у вас несколько субаккаунтов, и вы хотите протестировать API запросы в Mailchimp из другого аккаунта, который подключён к вашей учётной записи. Тогда при авторизации нужно менять только пароль — логин остаётся прежним.
Свой API key можете найти во вкладке Account → Extras → API keys:
Сам по себе API key является важной частью любого API запроса в Mailchimp и должен использоваться либо в теле запроса, либо при авторизации.
Это основная часть запроса. В ней прописываем, что хотим сделать. Например, если добавляем подписчика в список, то прописываем его почту, значение дополнительных полей, присваиваем различные параметры. В основном используют типы запросов JSON и XML.
В теле запроса важно правильно расставить синтаксис: закрыть скобки, где нужно, поставить запятую. Эти вещи легко упустить, если у вас нет опыта в составлении запросов, но без этого весь запрос будет некорректным.
Здесь Postman будет показывать ответ на запрос.
Если запрос не проходит по какой-то причине, в этой вкладке вы найдёте подробное описание ошибки. В ответ на успешный запрос чаще всего приходит статус 201 created, но это зависит от API платформы.
Основные параметры:
В моём примере это us17.
"email_address": "youremail@gmail.com",
"status": "subscribed",
"merge_fields": {
"FIRSTNAME": "",
"LASTNAME": ""
}
}
Основные параметры:
В примере используются только два дополнительных поля: имя и фамилия. По факту вы можете передавать любое значение в любое поле, которое есть у вас в платформе. Соответственно, если в вашей форме будет нестандартное поле, то его нужно сначала создать в Mailchimp, а уже потом прописывать передачу данных в запросе. Создаются такие поля во вкладке Merge Fields в настройках аудитории.
Там мы создаём дополнительные поля нужного нам типа. В запросе используем именно значения MERGE тегов, а не Field label and type. Нужный параметр выделен на скриншоте:
Таким образом, в запрос можно добавить столько дополнительных полей, сколько нужно. И следите за знаками препинания в запросе. После каждого поля ставим запятую, но в последнем поле запроса никакого знака стоять не должно. Если ошибиться, то запрос не пройдёт, а Postman вернёт сообщение с ошибкой. В программе достаточно легко заметить ошибку в синтаксисе — она будет выделена красным крестиком.
Таким же значком будут выделяться любые синтаксические ошибки: неправильно закрытые кавычки или скобки.
require_once('/path/to/MailchimpMarketing/vendor/autoload.php');
$Mailchimp = new \MailchimpMarketing\ApiClient();
$Mailchimp->setConfig([
'apiKey' => 'YOUR_API_KEY',
'server' => 'YOUR_SERVER_PREFIX'
]);
$email = "urist.mcvankab@example.com";
$list_id = "YOUR_LIST_ID";
try {
$response = $client->lists->addListMember($list_id, [
"email_address" => "prudence.mcvankab@example.com",
"status" => "subscribed",
"merge_fields" => [
"FNAME" => "Prudence",
"LNAME" => "McVankab"
]
]);
$response = $Mailchimp->lists->addListMember($list_id, $contact);
// TODO: Get the new member's ID from the response and echo it
//echo "Successfully added contact as an audience member. The contact's id is {$response->getId()}.";
} catch (MailchimpMarketing\ApiException $e) {
echo $e->getMessage();
}
Здесь у нас добавляются две новые переменные:
Сначала ищем workflow id:
https://<dc>.api.Mailchimp.com/3.0/automations/
В ответе Postman покажет данные по всем автоматизациям, которые есть в аккаунте. Нужная автоматизация будет иметь тип API 3.0. Её можно узнать и по теме письма.
Значение поля id — это как раз то, что нам нужно. Осталось узнать id письма. Для этого отправляем запрос:
https://<dc>.api.Mailchimp.com/3.0/automations/<workflow i>/emails
Получаем данные об автоматизации, там будет email id. После этого уже подставляем данные в первоначальный запрос и можем отправлять письмо.
"email_address": "youremail@gmail.com"
}
Здесь просто передаём email получателя. Чтобы письмо корректно отправилось, нужно, чтобы пользователь находился в нужном списке подписчиков. Поэтому в некоторых случаях делаем сразу несколько запросов, в том числе — на добавление подписчика в список.
Где <member_id> — почта подписчика, которому вы хотите присвоить тег, зашифрованный в md5 hash с помощью md5 Hash Generator. Скорее всего, Mailchimp шифрует данные для безопасности — чтобы в url запроса не передавать напрямую почту подписчика. Введите почту в поле сервиса и получите hash, который можно подставлять в url запроса.
"tags": [
{
"name": "product",
"status": "active"
}
]
}
Тело запроса очень простое. Статус должен стоять active, а в поле name мы прописываем тег, который хотим присвоить пользователю. Вся остальная информация, включая email пользователя, передаётся в url запроса.
$Mailchimp = new MailchimpMarketing\ApiClient();
$Mailchimp->setConfig([
'apiKey' => 'YOUR_API_KEY',
'server' => 'YOUR_SERVER_PREFIX'
]);
$list_id = "YOUR_LIST_ID";
$tag = new MailchimpMarketing\Model\List7();
$tag->setName("MegaInfluencer");
$tag->setStaticSegment(["dolly.parton@example.com", "rihanna@example.com"]);
try {
$response = $Mailchimp->lists->createSegment($list_id, $tag);
echo "Tag successfully created! Your tag id is " . $response->getId();
} catch (MailchimpMarketing\ApiException $e) {
echo $e->getMessage();
}
Источник статьи: https://habr.com/ru/post/563080/
API запросы нужны в email-маркетинге для того, чтобы передавать данные с сайта в платформу рассылок. Это может быть передача подписчиков в список, добавление им тегов, изменение значений дополнительных полей, отправка триггерных писем из платформы по запросу.
В сложных email-маркетинговых платформах всё строится на подобных запросах. Но даже в небольших проектах порой не хватает базовых интеграций, которые предлагает платформа, и нужно составлять кастомные API запросы.
Эта статья будет полезна для email-маркетологов, поможет им разобраться, как построить API запросы в Mailchimp и передать их в настройку для backend-разработчика. На сайте запрос настраивается в PHP — пример таких запросов мы тоже будем приводить, но более подробно разберём запросы, которые будет использовать маркетолог.
В теории email-маркетолог должен прочитать справку по API от Mailchimp и на её основе строить запросы и готовить ТЗ для запросов. На практике это может отнимать много времени и сил.
Разберу примеры API запросов в Mailchimp, которые можно будет протестировать. Можно брать примеры этих запросов, менять данные под свой проект и тестировать.
Подготовка к тестированию
Скачиваем Postman — программу для тестирования API запросов. В ней мы будем составлять запрос и отправлять его в платформу. Так проверим, корректен ли наш запрос и все ли данные приходят в платформу.Далее мы для каждого примера составим URL запроса, тело запроса и протестируем работу в Postman. А для некоторых — добавим пример запроса для PHP, который может потребоваться разработчику.
Вот из чего состоит интерфейс программы.
URL запроса
Здесь пишем URL запроса и метод. Чаще всего используются два метода запроса:
- POST, если нужно передать данные.
- GET, если нужно данные забрать. Например, если мы собираем отчёт по email каналу в Power BI, то будем использовать GET запросы.
Вкладка Authorization
Для доступа к платформе при выполнении некоторых запросов нужна авторизация. Обязательность её зависит от платформы, с которой вы работаете и от её API.
Например, при тестировании запросов в ExpertSender авторизация не нужна: все необходимые данные уже есть в запросе. Если мы работаем с API от Toggl, то должны авторизоваться Toggl-аккаунт. А вот для Mailchimp нужно использовать Basic Auth, где в качестве пароля будет использоваться индивидуальный идентификатор API key. Таким образом, во вкладке Username вы вводите свой логин или почту, а во вкладке Password — свой API key.
Возможно, у вас несколько субаккаунтов, и вы хотите протестировать API запросы в Mailchimp из другого аккаунта, который подключён к вашей учётной записи. Тогда при авторизации нужно менять только пароль — логин остаётся прежним.
Свой API key можете найти во вкладке Account → Extras → API keys:
Сам по себе API key является важной частью любого API запроса в Mailchimp и должен использоваться либо в теле запроса, либо при авторизации.
Тело запроса
Это основная часть запроса. В ней прописываем, что хотим сделать. Например, если добавляем подписчика в список, то прописываем его почту, значение дополнительных полей, присваиваем различные параметры. В основном используют типы запросов JSON и XML.
В теле запроса важно правильно расставить синтаксис: закрыть скобки, где нужно, поставить запятую. Эти вещи легко упустить, если у вас нет опыта в составлении запросов, но без этого весь запрос будет некорректным.
Response
Здесь Postman будет показывать ответ на запрос.
Если запрос не проходит по какой-то причине, в этой вкладке вы найдёте подробное описание ошибки. В ответ на успешный запрос чаще всего приходит статус 201 created, но это зависит от API платформы.
Запрос на операции с подписчиками: добавление, удаление, изменение
Используется при передаче подписчика в платформу с формы подписки или регистрации.URL запроса
https://<dc>.api.Mailchimp.com/3.0/lists/{list_id}/members/Основные параметры:
- {list_id} — уникальный id аудитории, куда вы добавляете подписчика, и найти его можно в настройках аудитории;
- dc — ваш сервер в Mailchimp: его можно найти в адресной строке.
В моём примере это us17.
Тело запроса
{"email_address": "youremail@gmail.com",
"status": "subscribed",
"merge_fields": {
"FIRSTNAME": "",
"LASTNAME": ""
}
}
Основные параметры:
- email_address — обязательное поле, почта подписчика;
- status — статус с которым передаём подписчика в список: нам нужен статус subscribed;
- merge_fields — дополнительные поля, которые прописываем пользователю при подписке.
- subscribed — даём команду подписывать человека на рассылки сразу;
- pending — отправить Double Opt-In (двойного подтверждения подписки) при попадании в список;
- unsubscribed — отписать пользователя от рассылки;
- cleaned — удалить из списка из-за невалидности контакта.
В примере используются только два дополнительных поля: имя и фамилия. По факту вы можете передавать любое значение в любое поле, которое есть у вас в платформе. Соответственно, если в вашей форме будет нестандартное поле, то его нужно сначала создать в Mailchimp, а уже потом прописывать передачу данных в запросе. Создаются такие поля во вкладке Merge Fields в настройках аудитории.
Там мы создаём дополнительные поля нужного нам типа. В запросе используем именно значения MERGE тегов, а не Field label and type. Нужный параметр выделен на скриншоте:
Таким образом, в запрос можно добавить столько дополнительных полей, сколько нужно. И следите за знаками препинания в запросе. После каждого поля ставим запятую, но в последнем поле запроса никакого знака стоять не должно. Если ошибиться, то запрос не пройдёт, а Postman вернёт сообщение с ошибкой. В программе достаточно легко заметить ошибку в синтаксисе — она будет выделена красным крестиком.
Таким же значком будут выделяться любые синтаксические ошибки: неправильно закрытые кавычки или скобки.
PHP запрос
Данный тип запроса пригодится backend разработчикам, когда они будут реализовывать скрипт запроса на сайте.require_once('/path/to/MailchimpMarketing/vendor/autoload.php');
$Mailchimp = new \MailchimpMarketing\ApiClient();
$Mailchimp->setConfig([
'apiKey' => 'YOUR_API_KEY',
'server' => 'YOUR_SERVER_PREFIX'
]);
$email = "urist.mcvankab@example.com";
$list_id = "YOUR_LIST_ID";
try {
$response = $client->lists->addListMember($list_id, [
"email_address" => "prudence.mcvankab@example.com",
"status" => "subscribed",
"merge_fields" => [
"FNAME" => "Prudence",
"LNAME" => "McVankab"
]
]);
$response = $Mailchimp->lists->addListMember($list_id, $contact);
// TODO: Get the new member's ID from the response and echo it
//echo "Successfully added contact as an audience member. The contact's id is {$response->getId()}.";
} catch (MailchimpMarketing\ApiException $e) {
echo $e->getMessage();
}
Отправка письма по запросу
URL запроса
https://<dc>.api.Mailchimp.com/3.0/automations/<workflow id>/emails/<email id>/queueЗдесь у нас добавляются две новые переменные:
- workflow id,
- email id.
Сначала ищем workflow id:
https://<dc>.api.Mailchimp.com/3.0/automations/
В ответе Postman покажет данные по всем автоматизациям, которые есть в аккаунте. Нужная автоматизация будет иметь тип API 3.0. Её можно узнать и по теме письма.
Значение поля id — это как раз то, что нам нужно. Осталось узнать id письма. Для этого отправляем запрос:
https://<dc>.api.Mailchimp.com/3.0/automations/<workflow i>/emails
Получаем данные об автоматизации, там будет email id. После этого уже подставляем данные в первоначальный запрос и можем отправлять письмо.
Тело запроса
{"email_address": "youremail@gmail.com"
}
Здесь просто передаём email получателя. Чтобы письмо корректно отправилось, нужно, чтобы пользователь находился в нужном списке подписчиков. Поэтому в некоторых случаях делаем сразу несколько запросов, в том числе — на добавление подписчика в список.
Присвоение тега подписчику
URL запроса
https:/<dc>.api.Mailchimp.com/3.0/lists/{list_id}/members/<member_id>/tagsГде <member_id> — почта подписчика, которому вы хотите присвоить тег, зашифрованный в md5 hash с помощью md5 Hash Generator. Скорее всего, Mailchimp шифрует данные для безопасности — чтобы в url запроса не передавать напрямую почту подписчика. Введите почту в поле сервиса и получите hash, который можно подставлять в url запроса.
Тело запроса
{"tags": [
{
"name": "product",
"status": "active"
}
]
}
Тело запроса очень простое. Статус должен стоять active, а в поле name мы прописываем тег, который хотим присвоить пользователю. Вся остальная информация, включая email пользователя, передаётся в url запроса.
PHP запрос
require_once('/path/to/MailchimpMarketing/vendor/autoload.php');$Mailchimp = new MailchimpMarketing\ApiClient();
$Mailchimp->setConfig([
'apiKey' => 'YOUR_API_KEY',
'server' => 'YOUR_SERVER_PREFIX'
]);
$list_id = "YOUR_LIST_ID";
$tag = new MailchimpMarketing\Model\List7();
$tag->setName("MegaInfluencer");
$tag->setStaticSegment(["dolly.parton@example.com", "rihanna@example.com"]);
try {
$response = $Mailchimp->lists->createSegment($list_id, $tag);
echo "Tag successfully created! Your tag id is " . $response->getId();
} catch (MailchimpMarketing\ApiException $e) {
echo $e->getMessage();
}
Источник статьи: https://habr.com/ru/post/563080/