🏠 Главная › Документация › Мессенджеры

Настройка Email

Hermes может получать и отвечать на электронные письма, используя стандартные протоколы IMAP и SMTP. Отправьте письмо на адрес агента, и он ответит в той же ветке — не требуется специальный клиент или API бота. Работает с Gmail, Outlook, Yahoo, Fastmail или любым провайдером, поддерживающим IMAP/SMTP.

info Без внешних зависимостей Адаптер Email использует встроенные модули Python imaplib, smtplib и email. Никаких дополнительных пакетов или внешних сервисов не требуется.

Предварительные требования

Настройка Gmail

  1. Включите двухфакторную аутентификацию в вашем аккаунте Google

  2. Перейдите в Пароли приложений

  3. Создайте новый пароль приложения (выберите «Почта» или «Другое»)

  4. Скопируйте 16-символьный пароль — вы будете использовать его вместо обычного пароля

Outlook / Microsoft 365

  1. Перейдите в Настройки безопасности

  2. Включите двухфакторную аутентификацию, если ещё не активирована

  3. Создайте пароль приложения в разделе «Дополнительные параметры безопасности»

  4. IMAP-хост: outlook.office365.com, SMTP-хост: smtp.office365.com

Другие провайдеры

Большинство почтовых провайдеров поддерживают IMAP/SMTP. Проверьте документацию вашего провайдера для получения:

Шаг 1: Настройка Hermes

Самый простой способ:

hermes gateway setup

Выберите Email в меню платформ. Мастер запросит ваш email-адрес, пароль, IMAP/SMTP-хосты и список разрешённых отправителей.

Ручная настройка

Добавьте в ~/.hermes/.env:

# Required
EMAIL_ADDRESS=hermes@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop    # App password (not your regular password)
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com

# Security (recommended)
EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com

# Optional
EMAIL_IMAP_PORT=993                    # Default: 993 (IMAP SSL)
EMAIL_SMTP_PORT=587                    # Default: 587 (SMTP STARTTLS)
EMAIL_POLL_INTERVAL=15                 # Seconds between inbox checks (default: 15)
EMAIL_HOME_ADDRESS=your@email.com      # Default delivery target for cron jobs

Шаг 2: Запуск Gateway

hermes gateway              # Run in foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

При запуске адаптер:

  1. Проверяет подключения к IMAP и SMTP

  2. Помечает все существующие сообщения во входящих как «прочитанные» (обрабатывает только новые письма)

  3. Начинает опрос новых сообщений

Как это работает

Получение сообщений

Адаптер опрашивает IMAP-входящие на наличие непрочитанных сообщений с настраиваемым интервалом (по умолчанию: 15 секунд). Для каждого нового письма:

Отправка ответов

Ответы отправляются через SMTP с правильной привязкой к веткам переписки:

Вложения

Агент может отправлять файлы в качестве вложений в ответах. Включите MEDIA:/path/to/file в ответ, и файл будет прикреплён к исходящему письму.

Пропуск вложений

Чтобы игнорировать все входящие вложения (для защиты от вредоносных программ или экономии трафика), добавьте в ваш config.yaml:

platforms:
  email:
    skip_attachments: true

При включении этой опции вложения и встроенные части пропускаются до декодирования полезной нагрузки. Текст письма по-прежнему обрабатывается в обычном режиме.

Контроль доступа

Доступ по email следует тому же шаблону, что и все остальные платформы Hermes:

  1. EMAIL_ALLOWED_USERS задан → обрабатываются только письма с этих адресов

  2. Белый список не задан → неизвестные отправители получают код для привязки

  3. EMAIL_ALLOW_ALL_USERS=true → принимаются любые отправители (используйте с осторожностью)

**Всегда настраивайте `EMAIL_ALLOWED_USERS`.** Без этого любой, кто знает email-адрес агента, сможет отправлять команды. По умолчанию агент имеет доступ к терминалу.

Устранение неполадок

Проблема Решение
«IMAP connection failed» при запуске Проверьте EMAIL_IMAP_HOST и EMAIL_IMAP_PORT. Убедитесь, что IMAP включён в аккаунте. Для Gmail включите его в Настройках → Пересылка и POP/IMAP.
«SMTP connection failed» при запуске Проверьте EMAIL_SMTP_HOST и EMAIL_SMTP_PORT. Убедитесь, что пароль указан верно (используйте пароль приложения для Gmail).
Сообщения не приходят Проверьте, что email отправителя указан в EMAIL_ALLOWED_USERS. Проверьте папку со спамом — некоторые провайдеры помечают автоматические ответы как спам.
«Authentication failed» Для Gmail необходимо использовать пароль приложения, а не обычный пароль. Убедитесь, что сначала включена двухфакторная аутентификация.
Дублирование ответов Убедитесь, что запущен только один экземпляр gateway. Проверьте hermes gateway status.
Медленный ответ Интервал опроса по умолчанию — 15 секунд. Уменьшите с помощью EMAIL_POLL_INTERVAL=5 для более быстрого ответа (но это увеличит количество IMAP-подключений).
Ответы не группируются в ветки Адаптер использует заголовки In-Reply-To. Некоторые почтовые клиенты (особенно веб-версии) могут неправильно группировать автоматические сообщения.

Безопасность

**Используйте выделенный почтовый аккаунт.** Не используйте личную почту — агент хранит пароль в `.env` и имеет полный доступ к почтовому ящику через IMAP.

Справочник переменных окружения

Переменная Обязательная По умолчанию Описание
EMAIL_ADDRESS Да — Email-адрес агента
EMAIL_PASSWORD Да — Пароль от почты или пароль приложения
EMAIL_IMAP_HOST Да — IMAP-сервер (например, imap.gmail.com)
EMAIL_SMTP_HOST Да — SMTP-сервер (например, smtp.gmail.com)
EMAIL_IMAP_PORT Нет 993 Порт IMAP-сервера
EMAIL_SMTP_PORT Нет 587 Порт SMTP-сервера
EMAIL_POLL_INTERVAL Нет 15 Интервал проверки входящих (в секундах)
EMAIL_ALLOWED_USERS Нет — Список разрешённых отправителей (через запятую)
EMAIL_HOME_ADDRESS Нет — Адрес доставки по умолчанию для cron-задач
EMAIL_ALLOW_ALL_USERS Нет false Разрешить всех отправителей (не рекомендуется)