API ключи и вебхуки

Mail Merge имеет REST API и исходящие вебхуки для разработчиков и создателей без кода. С API ключом ваши скрипты могут делать то же, что веб-приложение: читать ваш аккаунт, выводить список шаблонов и контактов, отправлять кампании и отслеживать их получателей. С вебхуком Mail Merge вызывает ваш endpoint в момент завершения кампании или когда получатель открывает письмо, кликает по ссылке, отвечает, письмо отскакивает или отписывается, поэтому CRM, таблица или канал Slack остаются в синхронизации без постоянных запросов.

Оба находятся в Settings → Developers в веб-приложении и входят в план Professional (см. Pricing). Если вы предпочитаете общаться с Mail Merge через AI ассистента вместо написания кода, используйте MCP server: он предоставляет те же функции в виде инструментов на любом плане.

API ключи

Создание ключа

1. Откройте Settings → Developers → API keys и нажмите Create key.
2. Назовите его в соответствии с местом использования (Zapier, CRM sync), чтобы позже можно было отозвать нужный.
3. Скопируйте ключ. Он показывается один раз: Mail Merge хранит только его хеш. Если вы потеряете ключ, отозовите его и создайте новый.

Вы можете иметь до 10 ключей на аккаунт. Отзыв ключа приводит к немедленному отказу всех запросов, сделанных с его использованием; строка исчезает из списка.

Аутентификация

Отправляйте ключ как Bearer токен в каждом запросе к базовому URL, показанному на карточке:

curl https://merge.email/api/v1/me \
  -H "Authorization: Bearer mm_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Ключ действует как аккаунт, который его создал, точно как авторизованная сессия: тот же Google грант, тот же дневной лимит, те же ограничения плана. Отдельного “API пользователя” нет.

Endpoints

API использует ту же поверхность /v1, что и веб-приложение, поэтому все, что вы можете сделать на экране, имеет endpoint позади. Те, к которым чаще всего обращаются интеграции:

Вызов	Что он делает
GET /v1/me	Аккаунт: план, дневной лимит (максимум, использовано, осталось), часовой пояс, метаданные шаблонов.
GET /v1/templates · GET /v1/templates/{templateId}	Ваши сохраненные шаблоны; тело загружается для каждого шаблона.
GET /v1/contacts · POST /v1/contacts	Адресная книга (разбита на страницы с limit / cursor → nextCursor).
POST /v1/campaigns	Отправьте, запланируйте или автоматизируйте кампанию из Google Sheet. Тело совпадает с тем, которое отправляет конструктор кампаний: таблица, столбец получателей, тема и текст с {{merge tags}} и параметры отправки.
GET /v1/campaigns · GET /v1/campaigns/{campaignId}/recipients	Ваши кампании и статус каждого получателя (отправлено, прочитано, кликнуто, ответ, отскок, отписано).
POST /v1/campaigns/{campaignId}/status	Приостановите, возобновите или остановите запущенную кампанию.
POST /v1/recipients/verify	Верификатор email.

Тела запросов и ответов в JSON. Полная типизированная поверхность генерируется с сервера как OpenAPI документ; свяжитесь с нами, если вам нужна схема для генератора клиента.

Ошибки и лимит частоты

Ошибки это реальные HTTP статусы с одной оболочкой:

{ "error": { "code": "professional_plan_required", "message": "API access is a Professional plan feature" } }

Статус	code	Значение
401		Неизвестный или отозванный ключ, или доступ Google аккаунта нужно переподключить.
403	professional_plan_required	Аккаунт ключа больше не на плане Professional. Ключи не удаляются при понижении; они работают снова, когда план активен.
429	rate_limited	Более 600 запросов в минуту на один ключ. Подождите минуту и повторите попытку.
400 / 404 / 409	bad_request, not_found, conflict, …	Сам запрос, с сообщением о том, что исправить.

Лимит частоты считается на каждый ключ на каждом экземпляре API сервера, поэтому эффективный потолок это “примерно 600 в минуту”: не проектируйте систему для достижения этого лимита.

Вебхуки

Добавление endpoint

1. Откройте Settings → Developers → Webhooks и нажмите Add webhook.
2. Введите HTTPS URL (простой http:// отклоняется) и отметьте события, которые он должен получать.
3. Нажмите Send test на новой строке: Mail Merge отправляет ping и всплывающее сообщение покажет, как ваш endpoint ответил.

Каждый endpoint получает свой signing secret (whsec_…), показанный на строке с кнопкой копирования. Вы можете иметь до 5 endpoints на аккаунт.

События

События	Когда	data
campaign.completed	Последнее письмо кампании было обработано.	campaignId, name, status: "completed", sentCount, campaignSize
campaign.paused · campaign.resumed · campaign.stopped	Вы приостановили, возобновили или остановили кампанию.	campaignId, name, status (paused / active / stopped), sentCount
email.opened	Получатель открыл письмо, только первый раз за кампанию.	campaignId, recipient, at
email.clicked	Получатель кликнул по отслеживаемой ссылке, каждый клик.	campaignId, recipient, at, url
email.replied	Ответ обнаружен в отправленной цепочке.	campaignId, recipient, at
email.bounced	Отскок обнаружен.	campaignId, recipient, at
recipient.unsubscribed	Получатель использовал ссылку отписки, только первый раз за кампанию.	campaignId, recipient, at, method

Открытия и клики требуют отслеживания для кампании; ответы и отскоки поступают из сканирования ответов, которое следует за каждой отправленной кампанией.

Доставка

Mail Merge отправляет один POST на событие на каждый подписанный endpoint с JSON телом:

{
  "id": "6f1c2d3e-…",
  "event": "email.opened",
  "createdAt": "2026-10-15T14:03:21.512Z",
  "data": { "campaignId": "…", "recipient": "ada@example.com", "at": "2026-10-15T14:03:21.498Z" }
}

и три заголовка:

Заголовок	Значение
X-MailMerge-Event	Имя события, совпадает с event в теле.
X-MailMerge-Delivery	ID доставки, совпадает с id. Используйте его для игнорирования дубликата.
X-MailMerge-Signature	sha256= с последующим hex HMAC-SHA256 сырого тела, ключ с секретом endpoint.

Ответьте любым 2xx в течение 5 секунд. При сетевой ошибке или 5xx Mail Merge повторяет попытку один раз, через 2 секунды; 4xx принимается как ваше решение и не повторяется. Тот же ID доставки отправляется при повторе. После 20 неудачных доставок подряд endpoint отключается и строка это показывает: исправьте endpoint, затем удалите и добавьте его снова. Любая успешная доставка сбрасывает счетчик.

События доставляются как минимум один раз и в не гарантированном порядке. Открытия в частности приходят волнами (каждый почтовый клиент, который отображает пиксель отслеживания), поэтому сделайте ваш обработчик идемпотентным на X-MailMerge-Delivery или на (event, campaignId, recipient).

Проверка подписи

Всегда проверяйте перед доверием к payload. Вычислите HMAC над сырым телом запроса (точные байты, перед любым JSON парсингом) и сравните в постоянное время:

// Node.js (Express с `express.raw({ type: "application/json" })`)
import { createHmac, timingSafeEqual } from "node:crypto"

export function verifyMailMergeSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? "")
  return a.length === b.length && timingSafeEqual(a, b)
}

app.post("/mailmerge", (req, res) => {
  if (!verifyMailMergeSignature(req.body, req.get("X-MailMerge-Signature"), process.env.MAILMERGE_WEBHOOK_SECRET)) {
    return res.status(401).end()
  }
  const payload = JSON.parse(req.body)
  // … handle payload.event / payload.data
  res.status(204).end()
})

# Python
import hashlib, hmac

def verify_mailmerge_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Zapier, Make и n8n

Код не требуется: создайте Catch Hook (Zapier Webhooks by Zapier), Custom webhook (Make) или узел триггера Webhook (n8n), вставьте URL, который он вам дает, как endpoint, отметьте события и нажмите Send test, чтобы инструмент мог получить образец payload. Поля data становятся переменными, которые вы отображаете на следующий шаг (добавьте строку в таблицу, обновите контакт CRM, опубликуйте в Slack). Эти инструменты не проверяют подписи по умолчанию; URL, который они вам дают, неугадываемый, это защита, на которую они полагаются.

Куда дальше

• AI agents (MCP), если ассистент должен управлять Mail Merge вместо скрипта.
• Campaigns, для понимания того, что означают статусы в endpoint получателей.
• Pricing, для информации о том, что включает план Professional.