Документация по функциональным возможностям почтовой платформы

EmailAdapter — это почтовый адаптер, основанный на протоколах SMTP/IMAP, поддерживающий отправку, получение и обработку электронной почты.

Информация о документации

• Версия соответствующего модуля: 4.2.0
• Ответственный: ErisPulse

Основная информация

• Краткое описание платформы: универсальный адаптер для отправки и получения почты через стандартные протоколы SMTP/IMAP
• Название адаптера: EmailAdapter
• Поддержка нескольких аккаунтов: поддерживает настройку нескольких почтовых аккаунтов одновременно
• Способ подключения: получение через IMAP-длинный опрос + отправка через SMTP
• Способ аутентификации: адрес электронной почты + пароль/код авторизации
• Совместимость с OneBot12: поддерживает отправку сообщений в формате OneBot12

Инструкция по конфигурации

Глобальная конфигурация (EmailAdapter)

Конфигурация аккаунта (EmailAdapter.accounts)

Каждый аккаунт соответствует отдельной электронной почте. Конфигурация аккаунта имеет приоритет над глобальной конфигурацией.

[EmailAdapter.accounts.default]
email = "[email protected]"
password = "your-password-or-auth-code"
imap_server = "imap.example.com"    # Опционально, оставьте пустым для использования глобального значения по умолчанию
imap_port = 993                      # Опционально
smtp_server = "smtp.example.com"    # Опционально
smtp_port = 465                      # Опционально
ssl = true                           # Опционально
timeout = 30                         # Опционально
enabled = true

[EmailAdapter.accounts.backup]
email = "[email protected]"
password = "another-password"
enabled = true

Обновление парадигмы v5 (4.2.0)

• Минимальный набор Api DSL: get_self_info (адрес электронной почты)/get_status/get_version/get_supported_actions
• Принадлежность задачи spawn_background: Задачи IMAP-опроса теперь используют runtime.spawn_background
• Мягкая зависимость от фреймворка: Проверка наличия ErisPulse>=2.7.1 во время выполнения с соответствующим сообщением; вывод логов версии при запуске
• Обновление путей импорта до Core.Bases; _load_accounts сохраняется (глобальные значения по умолчанию объединяются в логику, специфичную для этого адаптера)

Поддерживаемые возможности платформ

• Прием: Опрос IMAP для получения писем (анализ тела/HTML/вложений в сообщения), обнаружение новых непрочитанных писем
• Отправка: Отправка писем через SMTP (Subject/Text/Html/Cc/Bcc/ReplyTo/Attachment), поддержка нескольких учетных записей
• API: Информация о счетах и статус выполнения (минимальный набор); понятия отмены писем/группы не применимы

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

Все методы отправки реализованы с использованием цепочечного синтаксиса:

from ErisPulse.Core import adapter
mail = adapter.get("email")

# Простое текстовое письмо
await mail.Send.To("private", "[email protected]").Subject("Тест").Text("Содержание")

# HTML-письмо с вложениями
await mail.Send.To("private", "[email protected]") \
    .Subject("HTML-письмо") \
    .Cc(["[email protected]", "[email protected]"]) \
    .Attachment("report.pdf") \
    .Html("<h1>HTML-содержание</h1>")

# Использование Raw_ob12 для отправки стандартных сообщений OB12
await mail.Send.To("private", "[email protected]").Raw_ob12([
    {"type": "text", "data": {"text": "Текст письма"}},
    {"type": "file", "data": {"file": "/path/to/attachment.pdf"}},
])

# Указание учетной записи для отправки (множественные учетные записи)
await mail.Send.Using("default").To("private", "[email protected]").Text("Содержание")

Важно: при использовании цепочечного синтаксиса методы с параметрами (Subject / Cc / Attachment и т.д.) должны вызываться до методов отправки (Text / Html / Raw_ob12).

Основные методы отправки

Методы цепочечного синтаксиса (возвращают self, могут использоваться в комбинации)

Обратное преобразование OB12-сегментов сообщений (Raw_ob12)

Типы событий, специфичные для почты

Основные различия

1. Все почтовые события имеют тип message, а detail_type всегда равен private
2. user_id — это чистый адрес электронной почты отправителя, а user_nickname — отображаемое имя отправителя
3. Сегмент message сообщения имеет стандартный формат OB12 (сегмент text + сегмент file)
4. Тема письма доступна через расширенное поле email_subject
5. Полные исходные данные сохраняются в поле email_raw

Событие нового письма (email_new)

{
  "id": "<[email protected]>",
  "time": 1751990446,
  "type": "message",
  "detail_type": "private",
  "platform": "email",
  "self": {
    "platform": "email",
    "user_id": "[email protected]"
  },
  "message": [
    {
      "type": "text",
      "data": {
        "text": "Содержимое тела письма"
      }
    }
  ],
  "alt_message": "Тема письма",
  "user_id": "[email protected]",
  "user_nickname": "Saber"
}

Письмо с вложением

{
  "message": [
    {
      "type": "text",
      "data": {
        "text": "Пожалуйста, проверьте вложение"
      }
    },
    {
      "type": "file",
      "data": {
        "file_id": "document.pdf",
        "file_name": "document.pdf",
        "size": 102400
      }
    }
  ]
}

Событие ответа на письмо (email_reply)

Когда письмо содержит заголовки References или In-Reply-To, email_raw_type принимает значение email_reply:

{
  "email_raw_type": "email_reply",
  "email_raw": {
    "references": "<[email protected]>",
    "in_reply_to": "<[email protected]>"
  }
}

Описание расширенных полей

Примеры стандартных событий

Полное событие электронной почты

{
  "id": "<[email protected]>",
  "time": 1751990446,
  "type": "message",
  "detail_type": "private",
  "platform": "email",
  "self": {
    "platform": "email",
    "user_id": "[email protected]"
  },
  "message": [
    {
      "type": "text",
      "data": {
        "text": "Пожалуйста, проверьте вложение"
      }
    },
    {
      "type": "file",
      "data": {
        "file_id": "document.pdf",
        "file_name": "document.pdf",
        "size": 102400
      }
    }
  ],
  "alt_message": "Уведомление о встрече",
  "user_id": "[email protected]",
  "user_nickname": "Sender",
  "email_subject": "Уведомление о встрече",
  "email_from": "[email protected]",
  "email_raw": {
    "subject": "Уведомление о встрече",
    "from": "\"Sender\" <[email protected]>",
    "to": "<[email protected]>",
    "date": "Wed, 9 Jul 2026 02:00:46 +0800",
    "message_id": "<[email protected]>",
    "references": "",
    "in_reply_to": "",
    "cc": "",
    "bcc": "",
    "text_content": "Пожалуйста, проверьте вложение",
    "html_content": "<p>Пожалуйста, проверьте вложение</p>",
    "attachments": ["document.pdf"]
  },
  "email_raw_type": "email_new",
  "attachments": [
    {
      "filename": "document.pdf",
      "content_type": "application/pdf",
      "size": 102400,
      "data": "..."
    }
  ]
}

Возвращаемое значение метода отправки

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "message_id": "<[email protected]>",
    "time": 1751990446
  },
  "message_id": "<[email protected]>",
  "message": "",
  "email_raw": {
    "success": true,
    "message": "Email sent successfully"
  }
}

Пример обработки событий

from ErisPulse.Core.Event import message

@message.on_message()
async def handle_email(event):
    if event.get("platform") != "email":
        return
    # Адрес отправителя (только почта)
    sender = event["user_id"]              # [email protected]
    
    # Отображаемое имя отправителя
    nickname = event.get("user_nickname")  # Sender
    
    # Тема письма
    subject = event.get("email_subject")   # Уведомление о встрече
    
    # Текстовое тело (первый текстовый сегмент)
    text = event.get_text()
    
    # Полные исходные данные
    raw = event.get("email_raw", {})
    html = raw.get("html_content", "")
    
    # Обработка вложений
    for seg in event.get("message", []):
        if seg["type"] == "file":
            filename = seg["data"]["file_name"]
            size = seg["data"]["size"]
    
    # Ответ на письмо
    await event.reply(f"Получено: {subject}")