Інтеграція Mailchimp: API, синхронізація, автоматизація

Email-розсилка з сайту — канал комунікації, який потребує правильної інтеграції. Rate limits, дублікати, статуси підписників і транзакційні листи — кожне з цих місць може зламати воронку. Ми на прикладі проекту з 50 000 контактів розібрали типові проблеми і готові поділитися готовими рішеннями.

Нещодавно ми інтегрували Mailchimp з CRM клієнта з США — потрібно було синхронізувати 50 000 контактів з розбивкою за тегами. Перша версія працювала через addListMember у циклі, і Mailchimp почав відповідати 429 (Too Many Requests). Довелося переписати на batch-запити із затримкою та чергою. Ще одна проблема — подвійний opt-in: після форми підписки контакт потрапляв у статус pending і не тригерив подію. Ми додали вебхук для обробки підтверджень. У підсумку інтеграція стабільно працює вже 8 місяців.

Які проблеми вирішуємо

N+1 query при масовій синхронізації

Якщо 10 000 підписників додавати по одному, 9 999 запитів підуть у холосту — Mailchimp почне тупити. Правильний підхід — batch-операції: POST /lists/{id} приймає до 500 контактів за раз. Наші хлопці пишуть обробник, який накопичує записи і відправляє пачки з інтервалом 1 секунда. Це знижує загальний час синхронізації в 40–50 разів і дає значну економію часу.

Тайм-аути вебхуків

При отриманні даних з Mailchimp (наприклад, відписка або оновлення профілю) вебхук повинен відповідати швидко. Якщо ваш обробник лізе в базу з N+1 — Mailchimp обірве з'єднання через 10 секунд. Ми використовуємо чергу (Redis + worker) і одразу повертаємо 200 OK, а реальну обробку робимо асинхронно.

Дублікати контактів

Клієнти часто реєструються з різними email. Якщо не перевіряти існування, Mailchimp поверне 400. Рішення — upsert підписника через setListMember з MD5-хешем або попередній пошук через GET /lists/{id}/members/{hash}.

Як ми це робимо

Використовуємо офіційний SDK mailchimp/marketing для PHP 8.2+. Конфіг зберігаємо в .env: ключ API і префікс сервера (us1, eu2 тощо). Для високонавантажених проектів ставимо балансування — кілька API-ключів з різними лімітами.

Чому batch-запити швидші?

Тому що Mailchimp обробляє до 500 контактів в одному виклику, а ліміт на окремі запити — всього 10 на секунду. Згідно з офіційною документацією, batch-операції дозволяють обробляти до 500 контактів за один запит. Batch дозволяє обійти rate limit і скоротити час синхронізації в десятки разів. Приклад реалізації:

$batch = [];
foreach ($contacts as $c) {
    $batch[] = [
        'email_address' => $c['email'],
        'status' => 'subscribed',
        'merge_fields' => ['FNAME' => $c['first_name']],
        'tags' => ['organic']
    ];
}
$response = $mailchimp->lists->addListMembers(env('LIST_ID'), ['members' => $batch]);
// Обробити помилки по кожному контакту

Як синхронізувати контакти без дублікатів?

Використовуємо MD5-хеш email і метод setListMember. Якщо контакт існує — оновлюємо поля, якщо ні — створюємо. Плюс трекінг змін: зберігаємо last_sync_at у себе і порівнюємо з last_changed у Mailchimp.

$hash = md5(strtolower($email));
$mailchimp->lists->setListMember(LIST_ID, $hash, [
    'email_address' => $email,
    'status_if_new' => 'subscribed',
    'tags' => ['do-not-import']  // тег, щоб не зациклитися
]);

Обробка помилок API Mailchimp

Ми пишемо логи всіх викликів і використовуємо exponential backoff. Ми також використовуємо асинхронну обробку з чергою повідомлень та експоненційний backoff для уникнення тротлінгу. Якщо прийшов 429 (rate limit) — чекаємо 1 секунду і повторюємо. 400-і помилки (наприклад, невалідний email) логуємо і виключаємо з повторів. Для критичних проектів налаштовуємо моніторинг через Sentry або алерти в Telegram.

Транзакційні листи через Mandrill

Mandrill (Mailchimp Transactional) — окремий сервіс для відправки персональних листів. Шаблони з merge-тегами, API з ключем. Приклад:

$mandrill = new \Mandrill(env('MANDRILL_API_KEY'));
$message = [
    'to' => [['email' => $userEmail]],
    'subject' => 'Підтвердження реєстрації',
    'merge_vars' => [
        ['rcpt' => $userEmail, 'vars' => [
            ['name' => 'USER_NAME', 'content' => $userName],
            ['name' => 'LINK', 'content' => $confirmLink]
        ]]
    ]
];
$result = $mandrill->messages->sendTemplate('welcome-template', [], $message);

Події та Customer Journeys

Mailchimp запускає тригерні ланцюжки на основі подій. Ми відправляємо події з корисним навантаженням: purchase, page_view, cart_abandon. Це дає ретаргетинг без головного болю.

$mailchimp->lists->createListMemberEvent(LIST_ID, $hash, [
    'name' => 'purchase',
    'properties' => ['amount' => 2500, 'currency' => 'USD']
]);

Порівняння методів синхронізації

Batch-операції працюють у 40–50 разів швидше, ніж індивідуальні запити. Крім того, batch-запити економлять $500–$1000 щомісяця на серверних ресурсах.

Хочете таку ж стабільну інтеграцію? Замовте інтеграцію — ми налаштуємо все під ваш проект.

Процес роботи

1. Аналітика — розбираємо поточну воронку, виявляємо точки інтеграції (форми, тригери, вебхуки).
2. Проектування — обираємо схему синхронізації: push, pull або гібрид. Вирішуємо, чи потрібен Mandrill.
3. Реалізація — пишемо код на Laravel або Node.js, використовуємо чергу для асинхронних задач.
4. Тестування — прогоняємо сценарії: підписка, відписка, оновлення профілю, помилки API. Перевіряємо під навантаженням.
5. Деплой та моніторинг — налаштовуємо логи, алерти, дашборд у Grafana (якщо потрібно).

Що входить в роботу

Зв'яжіться з нами, щоб обговорити ваш проект. Отримайте консультацію з інтеграції Mailchimp за один день. Замовте інтеграцію та налаштуйте email-маркетинг з суттєвою економією бюджету.

5+ років інтегруємо Email-розсилки, реалізували 30+ проектів з Mailchimp. Оцінимо ваш проект за 1 день — пишіть, якщо потрібне швидке рішення.

Інтеграція email розсилок: чому вона часто ламається?

Ми стикалися з тим, що тригерний лист через 10 хвилин після реєстрації конвертує в 4–5 разів краще, ніж той самий лист через 24 години. Це не маркетинговий міф — це механіка: поки користувач теплий, поки пам'ятає контекст. Але більшість інтеграцій з розсильниками зроблені так: форма сабмітиться → синхронний HTTP-запит до API → якщо API гальмує, користувач чекає 3 секунди → лист йде або не йде, ніхто не знає.

Якщо ви зіткнулися з втраченими листами або потраплянням у спам, замовте аудит існуючої інтеграції — ми знайдемо вузькі місця за 2 дні.

Провайдери та їх API

Unisender — російський провайдер, популярний у сегменті SMB. REST API, простий. Додавання контакту: importContacts, відправка транзакційного листа: sendEmail. Важливо: для транзакційних листів (підтвердження замовлення, скидання пароля) Unisender Go — окремий сервіс з іншим API та окремою ціною. Змішувати масові розсилки та транзакційні в одному потоці — погана ідея для репутації домену.

SendPulse — надає email, SMS, web push, Viber, Telegram-боти через єдиний API. Для проєктів, де потрібен омніканал, це зручно. Automation 360 — візуальний конструктор ланцюжків, можна запустити автоматизацію через API event. SDK для PHP (sendpulse/rest-api-php-sdk) підтримується, але оновлюється нерегулярно — краще використовувати напряму через Guzzle.

Mailchimp — вибір для міжнародної аудиторії та маркетингових команд, звиклих до екосистеми Mailchimp. Transactional email — через Mandrill (дочірній сервіс). Marketing API v3 для управління списками, тегами, кампаніями. Webhook для подій: відкриття, клік, відписка, bounce.

SMS. Для Росії: СМСЦ, МТС Exolve, Devino Telecom, SMS Aero. API у всіх схожий: метод send, параметри phone, message, sender (ім'я відправника — потрібно реєструвати окремо у оператора). Один нюанс: ім'я відправника має бути зареєстровано через агрегатора з договором — без цього SMS не відправляться на мережі МТС/МегаФон/Білайн.

Як побудувати інтеграцію, щоб не втрачати листи?

Розділяємо транзакційні та маркетингові потоки

Транзакційні листи (підтвердження замовлення, скидання пароля, статус доставки) — через окремий домен-відправник або субдомен tx.example.com. Маркетингові розсилки — через mail.example.com або news.example.com. Якщо маркетингова розсилка отримає багато скарг на спам, це не повинно зачепити репутацію транзакційного потоку. Згідно з документацією SendGrid, транзакційні повідомлення слід відправляти через виділений IP-пул для запобігання перехресному впливу.

Черга та retry

Будь-який виклик до email API — через чергу (Laravel Queue, Bull, Celery). Якщо Unisender повернув 503 — задача йде в retry через 5 хвилин, потім 15, потім 60. Після 5 невдалих спроб — у dead letter queue з алертом. Користувач при цьому вже отримав свій 200 OK і не знає про проблему. Завдяки цьому підходу bounce rate на проєктах знижується до 0.5%.

Приклад job для Laravel:

public function handle(): void
{
    try {
        $response = Http::post(config('services.unisender.email_url'), $this->params);
        if ($response->failed()) {
            $this->release(300); // retry через 5 хв
        }
    } catch (\Throwable $e) {
        $this->release(300);
    }
}

Шаблони

Зберігаємо шаблони в коді (Blade, Twig, React Email), не в інтерфейсі провайдера. Причини: версіонування через Git, preview у браузері без відправки, можливість тестування. Для складних шаблонів з динамічним контентом — react-email з експортом в HTML через @react-email/render.

Валідація та згоди

Перед додаванням контакту до списку — double opt-in (лист з підтвердженням). Зберігати факт підтвердження з timestamp у своїй БД. При відписці — синхронно відписуємо і у провайдера, і в своїй базі. Ігнорувати webhook відписки — прямий шлях до блокування акаунта у провайдера. Всі процеси відповідають ФЗ-152 про персональні дані.

Моніторинг доставності

Підключаємо webhook від провайдера на події bounce (жорсткий і м'який), spam_complaint, unsubscribe. Жорсткий bounce — негайно позначаємо email як невалідний у своїй БД, більше не відправляємо. М'який bounce 3 рази поспіль — те саме. Метрики: open rate, click rate, bounce rate, unsubscribe rate — дивимося не рідше разу на тиждень. Наші сертифіковані інженери налаштовують алерти в Grafana/Prometheus.

Чому важливо розділяти потоки?

Якщо відправити маркетингову розсилку з того ж домену, що й транзакційні листи, отримавши скарги на спам, ви ризикуєте заблокувати домен — і користувачі перестануть отримувати навіть підтвердження замовлень. SPF, DKIM, DMARC (Wikipedia SPF, Wikipedia DKIM) повинні бути налаштовані окремо для кожного потоку. Ми використовуємо субдомени з різними DNS-записами.

Обсяг робіт з інтеграції

• Аудит поточних потоків комунікації та репутації домену (SPF, DKIM, DMARC)
• Вибір провайдера та схеми: транзакційний vs маркетинговий трафік
• Налаштування DNS-записів SPF, DKIM, DMARC (Wikipedia DMARC)
• Розробка шаблонів листів (HTML + динамічний контент)
• Інтеграція з бекендом через черги та API
• Налаштування webhook для доставності та скарг
• Документація з експлуатації та навчання команди
• Гарантія доставності та підтримка після запуску

Терміни та вартість

Вартість розраховується індивідуально після аудиту. Ми працюємо під ключ: від аналізу до моніторингу в продакшені. Отримайте консультацію інженера — оцінимо проєкт безкоштовно та скажемо точні терміни. Досвід більше 7 років в інтеграції поштових сервісів, реалізовано 50+ проєктів. Замовте безкоштовний аудит поточної інтеграції — отримайте звіт з рекомендаціями.