Google Postmaster API v2 и статус соответствия требованиям

1. Что изменилось в API v2 по сравнению с v1

Google Postmaster Tools API v2 стал общедоступным (general availability) 3 февраля 2026 года. В версии v1 основными данными были статистика трафика (TrafficStats): доля жалоб, доли прохождения SPF, DKIM и DMARC, ошибки доставки, а также категории репутации домена и IP (High, Medium, Low, Bad). В v2 Google перестроил набор данных вокруг соответствия требованиям отправителя: добавились методы статуса соответствия (compliance status), а репутация домена и IP как категория в API отсутствует.

Версия v1 не просто устарела, а отключена: обращение к ней возвращает HTTP 429 с текстом о том, что эта версия API больше не поддерживается. Внешне это выглядит как превышение лимита запросов, а не как выключение версии, поэтому интеграции, которые проверяют только код ответа, а не тело ошибки, читают отказ неверно и уходят в бесконечные повторы вместо перехода на v2.

Практический вывод: если ваш сервис или внутренняя панель до сих пор показывает "репутацию домена по Google", это либо кэш старых данных v1, либо внутренняя оценка самого сервиса, которую нельзя выдавать за данные Google. PostmastersTool собирает данные Google через API v2 и показывает доли SPF, DKIM, DMARC, долю жалоб и статус соответствия требованиям, без выдуманных баллов репутации.

2. Основные методы API v2

Набор методов v2 сгруппирован вокруг домена и его статистики. Ниже таблица соответствия, которую удобно держать под рукой при миграции кода.

Метод в v1 назывался domains.trafficStats.get и domains.trafficStats.list; в v2 ресурс trafficStats переименован в domainStats, а оба метода заменены одним domains.domainStats.query с диапазоном дат вместо запроса по одному дню.

Метод getComplianceStatus возвращает состояние домена относительно требований Gmail: вердикт по каждому требованию (SPF, DKIM, DMARC, формат письма, отписка и другие) и отдельный вердикт по доставляемости. Батчевого метода для статуса соответствия нет: getComplianceStatus принимает один домен за вызов. Батчем можно запросить только статистику (domainStats.batchQuery, до 100 доменов за вызов), что удобно для агентств и CRM-команд с десятками доменов отправки. Особенность батча: если хотя бы один домен в пачке недоступен вашему токену, весь вызов вернет ошибку доступа, а не частичный ответ, поэтому код должен уметь повторить запрос по доменам поодиночке и отдельно обработать недоступные.

Точные имена полей, единицы измерения и формат дат сверяйте по справочнику REST v2 в документации Google перед написанием кода. Не переносите структуру ответа v1 в новый адаптер без проверки: совпадение названия поля не гарантирует совпадение единицы измерения.

3. Как читать compliance status

Compliance status отвечает на вопрос: соответствует ли домен требованиям Gmail к отправителям. Это не оценка "хороший или плохой отправитель" в целом, а результат конкретных проверок: настроена ли аутентификация SPF, DKIM и DMARC, укладывается ли доля жалоб в пороги, соблюдены ли требования к отписке и формату писем.

Отдельно следите за единицами. Доля жалоб в данных API может приходить как доля единицы, а в требованиях Gmail пороги выражены в процентах: 0,1% как ориентир для стабильной доставки и 0,3% как верхняя граница. Преобразование в проценты выполняйте один раз, на границе отображения, и только после проверки, в какой единице конкретное поле отдает значение. Умножение любого числа на сто без проверки единицы это типичный источник "паники на пустом месте".

Два статуса, которые нужно различать в интерфейсе и в отчетах: статус соответствия требованиям Google, который приходит из API, и внутренний статус домена в вашем сервисе мониторинга, вычисленный по вашим порогам. Первый говорит, что видит Google, второй говорит, как вы настроили наблюдение. Смешение этих статусов в одной колонке приводит к ложным выводам при разборе инцидентов.

4. Переход с v1 на v2: пошаговый план

Миграция сводится к замене вызовов, пересмотру набора показателей и проверке прав доступа. Рабочая последовательность:

Шаг 1. Составьте список текущих вызовов v1 в вашем коде: какие методы, с какими параметрами, как часто. Отметьте, какие поля ответов реально используются в отчетах и интерфейсах.

Шаг 2. Сопоставьте каждому вызову метод v2 по таблице из раздела 2. Для показателей, которых в v2 нет (репутация домена и IP), решите, что показывать вместо них: честная подпись "показатель недоступен в API v2" лучше, чем заменяющее число.

Шаг 3. Проверьте область доступа OAuth и права сервисного аккаунта: разрешения должны соответствовать используемым методам v2. Проверка данных не требует прав на управление доменами, не расширяйте доступ без необходимости.

Шаг 4. Обновите адаптер, зафиксируйте преобразования единиц для каждого поля и правила обработки отсутствующих данных: неизвестное значение не должно подменяться нулем.

Шаг 5. Прогоните контрольный набор состояний (раздел 5) и сравните один и тот же день и домен в вашем сервисе и в веб-интерфейсе Postmaster Tools.

Шаг 6. Сохраните для поддержки: версию адаптера, описание преобразований, обезличенные контрольные примеры ответов. Токены и ответы частных аккаунтов в открытый репозиторий не включайте.

5. Контрольный набор состояний после миграции

После перехода проверьте не только успешный ответ, но и поведение системы на нестандартных состояниях. В контрольный набор включите:

Успешный ответ с полным набором полей. Отсутствие статистики за день (данные в Postmaster появляются при достаточном объеме трафика на Gmail и могут задерживаться). Частичный ответ, когда часть полей пуста. Ошибку доступа (неподтвержденный домен, отозванный OAuth). Временную ошибку API. Задержку данных, когда за вчерашний день статистика еще не опубликована.

Для каждого состояния зафиксируйте ожидаемое поведение интерфейса: пустое значение показывается как "нет данных", а не как ноль. Ноль вместо неизвестного значения это дефект: он искажает графики и может скрыть реальный рост жалоб или, наоборот, создать ложное ощущение порядка.

6. DKIM и статистика домена: что проверить при ротации ключей

Статистика Postmaster привязана к домену d= в подписи DKIM. Смена селектора s= выбирает другой ключ подписи, но при неизменном d= статистика остается привязанной к тому же домену и не переносится на другой. Это важно при ротации ключей и при переезде между ESP.

Если после ротации селектора возникла проблема, проверяйте в таком порядке: опубликован ли новый открытый ключ в DNS (запись вида selector._domainkey.example.com), подписывает ли отправляющая система новым ключом, проходит ли проверка DKIM в заголовках принятых писем. Для быстрой проверки заголовков используйте [анализатор заголовков письма](/tools/email-header-analyzer): в результатах Authentication-Results видно, какой d= и s= фигурируют в подписи и какой verdict вернул проверяющий сервер.

Отдельный случай: смена самого домена d=. Тогда статистика в Postmaster начинает накапливаться заново для нового домена, и это нормальное поведение, а не сбой API. Планируйте такие изменения с учетом того, что история по старому d= останется у старого домена.

7. Как встроить API v2 в регулярный мониторинг

Разовый запрос к API отвечает на вопрос "что сейчас", но не показывает динамику. Для рабочего контроля нужны: сбор данных по расписанию, история по дням, пороги с уведомлениями и раздельное отображение статуса Google и внутренних статусов.

PostmastersTool собирает данные Google Postmaster Tools через API v2 автоматически: доли SPF, DKIM, DMARC, доля жалоб и статус соответствия требованиям сохраняются по дням, а при пересечении порогов сервис присылает уведомление в выбранный канал (Telegram, почта и другие). Параллельно можно следить за Mail.ru Postmaster: объем, доставка, жалобы и показатель "Репутация, %", который отражает средний процент жалоб за 30 дней (меньше лучше).

Если доменов много, ручная сверка по каждому превращается в отдельную задачу. Сравнение ручной и автоматической проверки разобрано на странице [сравнения с ручной проверкой Postmaster](/compare/manual-postmaster-monitoring), а основной маршрут подключения описан на странице [мониторинга Google Postmaster](/google-postmaster-monitoring).