Главное про API key Mailchimp стоит знать до того, как ты его создашь: целиком ключ показывают ровно один раз — в момент генерации. Закрыл вкладку не скопировав — всё, этой строки больше нет. Дальше в интерфейсе останутся только имя ключа и его первые четыре символа.
Короткий маршрут выглядит так: иконка профиля → Profile → выпадающее меню Extras → API keys → кнопка Create A Key → имя ключа → Generate Key → Copy Key to Clipboard → Done. Минута работы, если знаешь, куда смотреть.
Ниже — тот же путь по шагам, что означает хвост вида -us6 в конце ключа, как за полминуты убедиться, что ключ живой, почему у части пользователей раздела API keys вообще нет и что отвечает сервер, когда с ключом что-то не так.
Один организационный момент: часть возможностей API привязана к платным планам, а тариф Mailchimp российской картой не оплатить.
Где в Mailchimp лежат API-ключи и как дойти до кнопки Create A Key
Ключи спрятаны не в настройках аккаунта, а в профиле конкретного пользователя. Кликаешь по иконке профиля, выбираешь Profile, открываешь выпадающее меню Extras и жмёшь API keys. Раздел так и называется — Your API Keys.
Расположение не случайное. Ключ принадлежит человеку, а не компании: если у пользователя отберут доступ к аккаунту, все созданные им ключи перестанут работать вместе с ним. Полезно помнить, когда ключ создаёт наёмный разработчик со своей учётки, а интеграция потом живёт годами.
В разделе видно не сами строки, а карточки: имя ключа и его первые четыре символа. Ключей у одного человека может быть несколько, и это нормальная практика. Различать их ты будешь только по именам, так что придумывать их наспех не стоит.
Пять шагов от Profile до строки ключа в буфере обмена
В разделе Your API Keys нажимаешь Create A Key. Первое, что попросят, — имя. Дальше Generate Key, затем Copy Key to Clipboard, и в конце Done.
На имени стоит задержаться. Позже ты будешь видеть только его и четыре первых символа ключа, так что «test» и «key1» через полгода не скажут тебе ничего. Пиши по назначению: «интеграция с CRM», «скрипт ночной выгрузки», «форма на сайте». Когда ключей станет пять, эта привычка сэкономит вечер.
Скопированную строку сразу клади туда, где ей место: менеджер паролей, переменные окружения на сервере, секреты в системе деплоя. Не в переписку, не в заметку на рабочем столе и не в файл рядом с кодом.
После Done строка исчезает навсегда. Проверить, что ты сохранил именно её, можно только одним способом — отправив запрос, и об этом чуть ниже.
Ключ показывают один раз — что делать, если не успел скопировать?
Восстановить его нельзя. Никакая поддержка не покажет тебе строку заново, потому что в открытом виде она нигде и не хранится.
Рабочий выход простой: создать новый ключ, вставить его в интеграцию, а старый отозвать. Отзыв делается кнопкой Revoke, и Mailchimp дополнительно требует ввести слово REVOKE в окне подтверждения — защита от промаха мышью. Отозванный ключ обратно не включается, он мёртв окончательно.
Сам я однажды отозвал не тот ключ — имена у двух были похожие, и в списке я промахнулся строкой. Через пару минут посыпались письма о том, что интеграция с сайтом отвалилась. Лечится это ровно так же: генерируешь новый, обновляешь настройки на стороне сайта, живёшь дальше. Неприятно, но не смертельно — при условии, что ты знаешь, какой ключ где используется.
Хвост -us6 в конце ключа: как по нему найти адрес своего API
Ключ Mailchimp заканчивается коротким хвостом через дефис: -us6, -us14, -us19. Это префикс дата-центра, на котором живёт твой аккаунт, и без него запрос уйдёт не туда.
Найти префикс можно тремя способами: посмотреть на хвост ключа, глянуть в адресную строку браузера в аккаунте (URL вида `https://us19.admin.mailchimp.com/` прямо называет дата-центр) или запросить его через OAuth Metadata endpoint, если интеграция работает по OAuth.
Именно на этом спотыкается половина первых запросов: ключ верный, синтаксис верный, а сервер отвечает отказом, потому что домен взят из чужого примера в документации.
На практике это выглядит так: за списком аудиторий запрос уходит на `https://us6.api.mailchimp.com/3.0/lists`, и меняется в этом адресе только префикс. Скопировал строку из примера с чужим дата-центром — получишь отказ, хотя ключ рабочий и права на месте.
Как за полминуты убедиться, что ключ рабочий
Для проверки есть служебный эндпоинт ping. Успешный ответ выглядит дружелюбно и ни с чем не спутаешь: `{"health_status": "Everything's Chimpy!"}`.
Аутентификация устроена двумя способами на выбор. Первый — базовая HTTP-авторизация, где логином идёт любая строка, а паролем сам ключ (формат `anystring:TOKEN`). Второй — заголовок `Authorization: Bearer <TOKEN>`. Токены API-ключа и OAuth 2 при этом работают одинаково, так что код под них пишется один.
В консоли проверка занимает одну строку: `curl -u anystring:ТВОЙ_КЛЮЧ https://us6.api.mailchimp.com/3.0/ping`. Вместо anystring подойдёт любое слово, значение имеет только пароль. Ответ приходит сразу — либо приветствие про Chimpy, либо код ошибки, и тогда дальше по списку.
Пришёл ответ про Chimpy — ключ живой и дата-центр угадан. Пришла ошибка — смотри, какая именно, они говорящие.
Почему в твоём аккаунте нет пункта API keys?
Потому что уровень доступа не тот. В Mailchimp пять ролей: Owner, Admin, Manager, Author и Viewer.
Добавлять API-ключи и видеть их могут только Admin и Manager. Author и Viewer этой возможности лишены — у них раздела просто нет. Отдельно устроен биллинг: менять платёжные данные разрешено только уровню Admin.
Так что если кнопки не видно, вопрос не к браузеру, а к владельцу аккаунта: нужно повышение до Manager или ключ, созданный кем-то с подходящими правами.
Ошибки 401, 403 и 429: что Mailchimp отвечает на плохой ключ
### 401: ключ не тот, отозван или отключён
Формулировка в документации прямая: ключ либо невалиден, либо отключён, а подробности лежат в поле detail. Практически всегда это опечатка при копировании, лишний пробел по краям строки или тот самый отозванный ключ, который остался в старом конфиге.
### 403: у пользователя нет доступа или прав на эндпоинт
Здесь ключ формально жив, но человек за ним — уже нет. Либо создатель ключа потерял доступ к аккаунту, либо его уровень прав не пускает к конкретному эндпоинту. Сюда же относятся ответы про деактивированный аккаунт и отсутствие права на запрошенную операцию.
Именно этот код обычно ловят команды, у которых интеграцию настраивал ушедший сотрудник. Ключ в конфиге лежит, вчера работал, сегодня — 403.
### 429: больше десяти одновременных запросов
Mailchimp разрешает не больше десяти одновременных подключений, и лимит считается на пользователя, а не на ключ. Завести под скрипт отдельный ключ и надеяться обойти ограничение не выйдет — лимит общий.
У 429 есть и второй повод: больше 500 ожидающих обработки вебхуков. Тогда нужно дождаться, пока очередь разгребётся, и только потом добавлять новые пакеты.
Из смежного стоит помнить про таймаут в 120 секунд на запрос и про код 426 — он приходит, когда соединение идёт без HTTPS или на устаревшей версии TLS. Поднять лимит подключений индивидуально нельзя, такой опции у сервиса нет.
### Когда ошибка вообще не про ключ
Часть кодов относится к самому запросу, а не к доступу. 400 приходит, когда сервер не разобрал тело запроса или получил недопустимые данные. 404 означает, что по такому адресу ресурса нет — чаще всего перепутан идентификатор аудитории. 405 — выбран неподходящий метод, скажем POST там, где ждут GET.
Смысл простой: не меняй ключ, увидев красный ответ. Сначала посмотри код — три цифры честно говорят, кто виноват: ключ, права, лимит или твой собственный запрос.
Ключ для транзакционных писем — другой ключ и другое место
Если тебе нужны письма о заказе, коде подтверждения или сбросе пароля — это Mailchimp Transactional, бывший Mandrill, и ключ у него собственный. Маркетинговый ключ там не подойдёт.
Создаётся он внутри аккаунта Transactional: Settings → раздел API Keys → Create New Key, дальше описание и та же история с однократным показом строки. База для запросов другая — `https://mandrillapp.com/api/1.0/`.
Доступ к Transactional тоже отдельный: нужен либо самостоятельный аккаунт этого продукта, либо тариф Standard и выше, на котором Transactional включается со страницы Monthly plans or credits.
Когда нужен OAuth 2
Ключ годится, пока ты ходишь в собственный аккаунт. Как только интеграция должна работать от имени других пользователей Mailchimp — например, ты делаешь публичное приложение, — ключи не подходят, там нужен OAuth 2.
Сколько ключей заводить на один проект
Правило от разработчиков сервиса: отдельный ключ на каждую интеграцию. Причина не в порядке ради порядка. Ключ даёт полный доступ к аккаунту, и когда один и тот же ключ вставлен в сайт, CRM и три скрипта, любая утечка означает замену во всех пяти местах разом, с простоем всего сразу.
Отсюда же запреты: не зашивать ключ в мобильное приложение и в код, который выполняется на стороне браузера, не отправлять его почтой, не хранить в публичном репозитории. Всё, что уходит на клиент, считай опубликованным.
Прав у самого ключа не бывает: режима «только чтение» или доступа к одной-единственной аудитории в Mailchimp нет. Ограничение приходит с другой стороны — от уровня пользователя, который этот ключ выписал. Ключ, созданный менеджером, упрётся в 403 там, где требуется админ, и это единственный доступный способ сузить его возможности.
### Можно ли выдать ключ подрядчику и потом закрыть доступ?
Можно, и механика тут удобная: ключи, созданные пользователем, перестают работать, когда у этого пользователя забирают доступ к аккаунту. Значит, правильный порядок — дать подрядчику собственную учётку уровня Manager, пусть он генерирует ключ себе сам. Закончилась работа — убираешь пользователя, и его ключи гаснут автоматически, без ревизии конфигов.
Что делать, если ключ утёк в публичный репозиторий?
Отзывать немедленно, до разбирательств. Открываешь Profile → Extras → API keys, жмёшь Revoke у нужной строки, вводишь REVOKE, генерируешь новый ключ и обновляешь интеграции.
Спешка тут оправдана: ключ — это полный доступ к аккаунту. Чужие руки могут выгрузить базу подписчиков, отправить рассылку от твоего имени или поменять автоматизации. Ещё один побочный эффект — тот самый лимит в десять одновременных подключений: посторонний скрипт способен выесть его целиком, и твои собственные интеграции начнут получать 429 на ровном месте.
Хорошая привычка на будущее — обращаться с ключом как с паролем, который ты выписал сам себе: раз в несколько месяцев менять, держать по одному на интеграцию и хотя бы примерно знать, какой из них где вставлен. Тогда любая утечка стоит пяти минут и одной кнопки, а не вечера в панике.
Комментарии
Войдите, чтобы написать комментарий