Почтовые агенты: отдельный email в Google Workspace, Microsoft 365, Яндекс 360 и Cloudflare

Подключить ИИ-агента можно к отдельному ящику почти в любой корпоративной почте. Для Google Workspace и Microsoft 365 удобнее использовать официальные API и уведомления о событиях, для Яндекс 360 и других IMAP-провайдеров — отдельный ящик с IMAP/SMTP, а для независимого агентного адреса — Cloudflare Email Routing и Worker.

Материал рассчитан на владельцев продукта, технических руководителей и разработчиков, которым нужно выбрать архитектуру и безопасно запустить первый почтовый процесс. Технические сведения по Gmail, Microsoft Graph и Cloudflare заново проверены по официальной документации 3 октября 2026 года.

API — программный интерфейс почтового сервиса. OAuth выдаёт приложению ограниченное разрешение без передачи основного пароля; scopes задают разрешённые операции. Push и webhook сообщают об изменении, IMAP читает ящик, SMTP отправляет письма, а IDLE ждёт изменения по открытому IMAP-соединению. Для реализации схемы нужны разработчик, доступ администратора к нужной почтовой системе и заранее выбранный способ хранения данных.

Какой способ подключения выбрать

Уведомления от почтового сервиса сокращают задержку и число запросов, но не отменяют синхронизацию состояния. Например, Gmail предупреждает, что push-сообщения иногда задерживаются или теряются, поэтому приложению нужен резервный периодический вызов history.list.

Рабочий контур одинаков для всех вариантов:

flowchart LR
    A["Письмо на отдельный адрес"] --> B["Проверка и дедупликация"]
    B --> C["Классификация и извлечение полей"]
    C --> D["Черновик ответа"]
    D --> E["Задача или запись в рабочей системе"]
    E --> F["Подтверждение человеком"]

Что должен делать почтовый агент

Полезный почтовый агент работает с конкретным процессом и отдельным адресом. Он может:

• читать тему, тело, отправителя, цепочку и разрешённые вложения;
• определять тип обращения;
• извлекать имена, компании, суммы, сроки и другие нужные поля;
• готовить черновик ответа или уточняющие вопросы;
• создавать карточку в CRM, тикет или задачу;
• передавать рискованные действия человеку.

Безопасный режим для первого запуска: агент готовит черновики и структурированные заметки, а человек подтверждает отправку.

Чеклист перед запуском

Google Workspace: Gmail API и Pub/Sub

Для отдельного корпоративного ящика рабочая схема выглядит так:

1. Создайте адрес, например leads@company.com.
2. Авторизуйте приложение для нужного ящика.
3. Создайте тему и подписку Cloud Pub/Sub.
4. Разрешите сервисному аккаунту Gmail публиковать сообщения в тему.
5. Вызовите users.watch для метки INBOX.
6. Сохраните исходный historyId из ответа watch. При уведомлении вызовите history.list со своим последним обработанным startHistoryId, обработайте все страницы изменений и только после успешной записи результата обновите сохранённую отметку.
7. Создайте черновик, поставьте метку или передайте данные в рабочую систему.

Актуальный пример запроса из документации Gmail:

POST https://www.googleapis.com/gmail/v1/users/me/watch
Content-Type: application/json

{
  "topicName": "projects/my-project/topics/gmail-inbox",
  "labelIds": ["INBOX"],
  "labelFilterBehavior": "INCLUDE"
}

Для запроса нужен заголовок Authorization: Bearer <access_token> с подходящим Gmail scope; имя Pub/Sub topic относится к тому же Google Cloud project, что вызывает watch. Разрешение на публикацию выдаётся gmail-api-push@system.gserviceaccount.com.

В ответ Gmail возвращает текущий historyId и время истечения подписки. Само уведомление содержит адрес ящика и новый historyId, а не полное письмо; при push JSON находится в Base64URL-поле message.data Pub/Sub. messageId Pub/Sub и идентификатор письма Gmail — разные значения. Если старая отметка истории уже недоступна и API возвращает 404, выполните полную синхронизацию ящика, затем сохраните новую отметку.

У Gmail действует ограничение: не более одного уведомления в секунду для отслеживаемого пользователя. Уведомления могут задерживаться или теряться. Храните последний обработанный historyId, делайте операции идемпотентными и запускайте резервную синхронизацию после периода без событий.

Подтверждайте Pub/Sub-уведомление только после того, как надёжно сохранили его для обработки: успешный HTTP-ответ означает acknowledgement. Повторная доставка возможна, поэтому обработка и создание черновика должны быть идемпотентными — повтор события даёт тот же результат, без второй записи.

Для пилота обычно достаточно пользовательского OAuth для одного ящика. Делегирование доступа на уровне домена (domain-wide delegation) даёт приложению более широкий административный доступ, поэтому требует минимальных scopes, отдельного сервисного аккаунта, ограничения списка ящиков и аудита.

Если прямой API-доступ нежелателен, используйте маршрутизацию: оставьте письмо в Gmail и отправляйте копию на агентный адрес либо маршрутизируйте только выбранные сообщения.

Официальные источники:

• Gmail API: push notifications
• Gmail API: users.watch
• Domain-wide delegation
• Маршрутизация почты Google Workspace

Microsoft 365: Microsoft Graph и shared mailbox

Для заявок, поддержки, тендеров и внутренних сервисных адресов удобно использовать общий ящик (shared mailbox), к которому обращаются сотрудники и интеграции:

1. Создайте общий ящик, например requests@company.com.
2. Зарегистрируйте приложение в Microsoft Entra ID.
3. Для подписки на shared/delegated mailbox выдайте соответствующие application permissions и ограничьте приложение нужным ящиком. Mail.Read.Shared и похожие delegated sharing scopes не поддерживают такие подписки.
4. Создайте подписку Microsoft Graph на новые сообщения в папке Inbox.
5. Проверьте запрос валидации endpoint.
6. При уведомлении получите сообщение либо используйте уведомления с данными ресурса (rich notifications), где содержимое передаётся в зашифрованном виде.
7. Создайте черновик или запись в рабочей системе.

Поддерживаемый путь ресурса для входящих сообщений имеет вид:

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created",
  "notificationUrl": "https://your-app.example.com/graph-webhook",
  "resource": "users/requests@company.com/mailFolders('inbox')/messages",
  "expirationDateTime": "<допустимое время истечения>",
  "clientState": "<случайное секретное значение>"
}

К запросу добавьте Authorization: Bearer <access_token> приложения с разрешением для выбранного ресурса. Вместо времени-заглушки укажите реальный UTC timestamp.

При создании подписки Graph отправляет POST с query-параметром validationToken. Верните URL-decoded значение в теле 200 OK с Content-Type: text/plain в течение 10 секунд. Не оборачивайте его в JSON. Это проверяет endpoint при регистрации и не удостоверяет последующие события.

expirationDateTime нельзя считать постоянным: подписку нужно продлевать заранее и отслеживать lifecycle notifications. Для Outlook message справочник задаёт границу 10 080 минут (семь суток), для rich notifications — 1 440 минут (сутки). Выбирайте срок с запасом до границы, сохраняйте subscription ID и фактическое время истечения из ответа.

Обычные уведомления быстро проверяйте и ставьте в надёжную очередь. В текущем контракте endpoint должен отвечать в пределах трёх секунд: 200, если обработка завершена, либо 202, если событие сохранено в очередь. Не подтверждайте событие до сохранения. Слишком медленный endpoint может получать задержки и пропуски; одной повторной доставки недостаточно для гарантии восстановления.

Для операций в собственном ящике от имени пользователя обычно используют делегированные права. Подписка на общий ящик требует правил, указанных выше. Фоновый сервис обычно использует права приложения (application permissions), поэтому область доступа особенно важно ограничить средствами Microsoft 365 или Exchange Online.

Официальные источники:

• Microsoft Graph Mail API
• Change notifications для Outlook
• Уведомления с данными ресурса
• Exchange Online mail flow rules

Яндекс 360 и другие IMAP/SMTP-провайдеры

Для Яндекс 360 базовая схема состоит из отдельного ящика, IMAP для чтения и SMTP для отправки. Яндекс поддерживает OAuth/XOAUTH2 для обоих протоколов. Для чтения выбирайте mail:imap_ro, для чтения и удаления — mail:imap_full, для отправки — mail:smtp; не выдавайте полные права, если агент только читает. Адреса серверов и разрешение использования почтового клиента проверьте в настройках конкретной организации.

При отсутствии у конкретного тарифа готового потока событий уровня Gmail Pub/Sub или Microsoft Graph интеграции нужен собственный контроль состояния:

• опрос ящика либо IMAP IDLE;
• хранение UID (идентификатора письма внутри папки) вместе с UIDVALIDITY (версией пространства этих идентификаторов) для каждой папки;
• дедупликация по идентификаторам сообщения и внутреннему ключу операции;
• восстановление после разрыва IMAP-соединения;
• отдельная обработка перемещений между папками;
• контроль неопределённого результата SMTP: если соединение оборвалось после передачи письма, оно могло быть принято. Не отправляйте его автоматически ещё раз без проверки журнала и состояния операции.

Условия тарифов и доступность протоколов могут меняться. Перед внедрением проверьте их для конкретного тарифа и организации по актуальной документации провайдера.

Источники для проверки Яндекс 360:

• OAuth для Яндекс Почты
• Правила обработки писем
• API Яндекс 360
• Стандарт безопасной работы Яндекс 360

Для одного-двух ящиков Mail.ru, VK WorkMail или другого провайдера прямое подключение по IMAP/SMTP может быть достаточным. Для множества клиентских подключений стоимость поддержки разных реализаций быстро растёт.

Cloudflare Email Service: отдельный агентный адрес

Cloudflare Email Routing принимает сообщения домена и передаёт их на подтверждённый внешний адрес либо в обработчик Worker. Такой вариант удобен для отдельного адреса вроде brief@ai.company.com, когда основную корпоративную почту переносить не нужно.

Email Routing обрабатывает входящую почту и доступен на Free и Paid. Отдельная функция Email Sending для отправки произвольным получателям находится в бете и требует Workers Paid: 3 000 писем в месяц включены, далее $0.35 за 1 000. Отправка на подтверждённые destination addresses в собственном аккаунте бесплатна на всех планах. Worker, хранилище и модель имеют собственные расходы. Это не полноценный ящик с IMAP, папками и готовой историей переписки. Статус и тариф.

Для работы Email Service домен должен использовать Cloudflare DNS. При подключении корневого домена Cloudflare добавляет MX-записи для входящей почты, а также записи SPF и DKIM. Изменение DNS может распространяться до 24 часов, хотя для доменов на Cloudflare обычно занимает 5–15 минут.

Минимальный путь:

1. Подключите домен или выделенный поддомен к Cloudflare DNS.
2. Выполните onboarding в разделе Email Routing.
3. Создайте Worker с обработчиком email.
4. Добавьте правило для нужного локального адреса.
5. Выберите действие Send to a Worker.
6. Отправьте тестовое письмо с другого адреса и проверьте журнал Worker или целевой ящик.

export default {
  async email(message) {
    const sender = message.from;
    const recipient = message.to;
    const subject = message.headers.get("subject") || "";

    console.log(JSON.stringify({
      event: "email_received",
      rawSize: message.rawSize,
      hasSubject: Boolean(subject),
    }));
  }
};

Этот пример только проверяет вызов обработчика по безопасной сводке: событие, размер и наличие темы. sender и recipient доступны коду, но не выводятся. Здесь нет forward, хранения письма или черновика ответа: не рассчитывайте, что письмо автоматически появится во внешнем ящике. Для пилота отправляйте синтетические письма и сохраняйте копию в действующей почтовой системе. Полное тело находится в message.raw как MIME-поток — формат с частями письма и их кодировками; для multipart и кодировок используйте подходящий MIME-парсер, например рекомендованный документацией postal-mime. Обработку тела письма, вызов модели и хранилище добавьте в этот обработчик по правилам вашей архитектуры; конкретные привязки окружения в примере не задаются.

Официальные источники:

• Cloudflare Email Service
• Настройка маршрутизации писем
• Обработчик входящих сообщений
• Agentic Inbox

Когда выбрать helpdesk или единый почтовый API

Helpdesk подходит, если письмо уже является обращением поддержки. Zendesk, Front, Freshdesk и Intercom дают очереди, роли, SLA, историю клиента и эскалацию. Собственный агент полезнее для нестандартных процессов: инвестиционных заявок, тендеров, договоров или кадрового intake.

Unified email API сокращает число отдельных интеграций с Gmail, Outlook, Exchange и IMAP. Примеры: Nylas, Unipile и EmailEngine.

У прослойки появляется доступ к почте клиентов. До выбора проверьте модель хранения данных, OAuth scopes, экспорт журналов, юрисдикцию, удаление данных и стоимость на один подключённый ящик.

Практические комбинации

Первый работающий процесс и его проверка

Начните с одного адреса и одного типа писем. Агент должен классифицировать письмо, извлекать заранее заданные поля, создавать черновик и передавать результат человеку.

Проверка результата:

1. Отправьте тестовое письмо с уникальным идентификатором в теме.
2. Убедитесь, что обработка началась один раз.
3. Сравните извлечённые поля с ожидаемыми.
4. Проверьте, что создан черновик, но письмо не отправлено автоматически.
5. Повторно доставьте то же событие и убедитесь, что дубль не создан.
6. Временно остановите приём событий, затем проверьте восстановление состояния.
7. Убедитесь, что в журнале нет тела секретов, OAuth-токенов и лишних персональных данных.

Что делать, если агент пропускает или дублирует письма

• Gmail перестал присылать события: проверьте expiration, ежедневное продление watch, права Pub/Sub и последний сохранённый historyId.
• Gmail пропустил уведомление: выполните синхронизацию через history.list; push не является единственным источником состояния.
• Microsoft Graph повторяет доставку: отвечайте endpoint в требуемый срок, проверяйте subscriptionId и делайте обработку идемпотентной.
• Microsoft Graph прислал неизвестное уведомление: не запускайте бизнес-логику до проверки subscriptionId и clientState; для rich notifications дополнительно проверьте JWT и зашифрованное содержимое. Query-параметр validationToken применяется при регистрации endpoint и не заменяет эти проверки.
• IMAP создаёт дубли: сверяйте UID вместе с UIDVALIDITY и храните собственный ключ обработанной операции.
• Cloudflare не принимает письмо: проверьте Cloudflare DNS, MX-записи, правило маршрутизации и выбранный Worker.
• Ответ попал не в ту цепочку: сохраняйте Message-ID и корректно формируйте In-Reply-To и References.
• Агент следует командам из письма: отделите системные правила от содержимого письма и запретите модели самостоятельно расширять права или вызывать рискованные действия.

Риски и стоп-линии

Письмо, HTML и вложения являются внешними недоверенными данными. Они могут содержать вредные инструкции для модели или попытки получить доступ к другим системам.

Для писем с персональными данными граждан РФ отдельно проверьте требования 152-ФЗ к локализации и трансграничной передаче. Конкретная схема зависит от ролей участников, состава данных и инфраструктуры. До запуска зарубежного почтового или AI-сервиса её следует проверить с профильным юристом; этот материал не является юридической консультацией.

Итог

Для Google Workspace используйте Gmail API, Pub/Sub и периодическую сверку истории. Для Microsoft 365 подходит shared mailbox с Microsoft Graph, продлением подписок и обязательной проверкой уведомлений. Для Яндекс 360 и других традиционных провайдеров потребуется устойчивый IMAP/SMTP-контур. Cloudflare удобен для отдельного агентного домена или поддомена, если вы готовы управлять DNS и Worker.

Первый рабочий результат — один адрес, один процесс, структурированная запись и черновик ответа с подтверждением человеком.

Следующий шаг

Начните с безопасной настройки домена и почты: Cloudflare для своего сайта.

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov