メールプラットフォームの機能ドキュメント

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": "メールの送信に成功しました"
  }
}

イベント処理の例

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 ブロック）
    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}")