Мы тестируем API запросы в Mailchimp заранее, чтобы успешно интегрировать платформу с сайтом.

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 запросы.

Примеры того, что вводим в поле для URL, будут чуть ниже.

Вкладка 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.

Это уникальные идентификаторы автоматизации и письма соответственно. Найти их можно с помощью двух GET запросов. Если POST запрос отравляет что-то вроде команд в систему и говорит, что надо сделать, то GET запрос забирает данные. Меняется тип запроса рядом с url:

Сначала ищем 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();
}

Желаем успешных интеграций!

Как тестировать API запросы в Mailchimp