slab-email

AIエージェント向けのヘッドレスメールコネクタ（RESTおよびMCP対応）

slab-emailは、正規化されたAPIとMCPツールサーフェスを介してメールボックスへのアクセスを標準化する、ローカルファーストのマイクロサービスです。

これは、複数のメールアカウントへの制御されたアクセスと安全な認証情報の処理を必要とするslab-agentsやその他のAIランタイム向けに設計されています。

これは何ですか？

slab-emailはメールUIではありません。

提供するもの：

• メールプロバイダーに対する正規化された読み取り/検索/作成/送信機能。

• アカウントおよびアクセスプロファイル管理のための管理REST。

• LLM/ツールクライアント向けのMCPサーバー。

• 以下のプロバイダーアダプター：

  • Proton（Proton Mail Bridge経由、必須）

  • 汎用IMAP/SMTP

  • Gmail（OAuth2 + Gmail API経由）

• SQLiteでの暗号化された認証情報ストレージ。

• プロファイルごとの機能を持つスコープ付きコネクタトークン。

• 送信の冪等性と基本的なアンチループレート制限。

アーキテクチャ

高レベルフロー：

• slab-agentsがスコープ付きコネクタトークンを使用して/mcpを呼び出します。

• REST管理エンドポイントがプロバイダーとアクセスプロファイルを設定します。

• アカウントはSQLiteに保存され、認証情報は保存時に暗号化されます。

• リクエスト時に、アカウント設定と復号化されたシークレットからプロバイダーインスタンスが作成されます。

• slab-emailはプロバイダーAPI（IMAP/SMTPまたはGmail API）に対して操作を実行します。

slab-agents (REST/MCP) -> slab-email
                             |
                             +-> sqlite (config + encrypted secrets)
                             +-> providers
                                 + proton_bridge -> Proton Mail Bridge (local IMAP/SMTP)
                                 + imap_smtp    -> Any IMAP/SMTP
                                 + gmail        -> Gmail API (OAuth2)

機能

• マルチアカウント対応：

  • 複数のアカウントを同時に接続および管理。

• プロバイダー抽象化：

  • Proton Bridge + IMAP/SMTP汎用 + Gmail。

• コネクタスコープの権限：

  • 読み取り / 下書き / 送信。

• idempotencyKeyによる冪等な送信/返信。

• スレッド化された読み取り/リストペイロードと完全なメッセージハイドレーション。

• AES-256-GCMを使用した暗号化シークレット。

• プロファイルにスコープされたアクセストークン。

• トークン要件によって分離された管理APIとMCP API。

• DockerおよびCI対応。

スタック

• Node.js + TypeScript

• Express 5

• SQLite（better-sqlite3）

• Zod

• MCP SDK（@modelcontextprotocol/sdk）

• IMAP/SMTP：imapflow、nodemailer

• Gmail：googleapis / google-auth-library

クイックスタート

1) ローカルサービスの起動

npm install
cp .env.example .env

.envに値を設定して実行：

export SLAB_EMAIL_ADMIN_KEY=change-me
export SLAB_EMAIL_MASTER_KEY=<32-byte base64 or 64-hex key>
npm run dev

期待される動作：

• GET /health → {"status":"ok"}。

• /mcpがPOST /mcpで利用可能。

2) スコープ付きプロファイルとトークンの登録

アカウント/プロファイル管理には管理トークンを使用し、通常の使用にはコネクタトークンを使用します。

設定

必要な/関連する環境変数：

• HOST（デフォルト 127.0.0.1）

• PORT（デフォルト 6981）

• DATABASE_PATH（デフォルト ./data/slab-email.db）

• SLAB_EMAIL_ADMIN_KEY（必須）

• SLAB_EMAIL_MASTER_KEY（必須、32バイトキー）

• GOOGLE_CLIENT_ID

• GOOGLE_CLIENT_SECRET

• GOOGLE_REDIRECT_URI（デフォルト http://127.0.0.1:6981/api/oauth/google/callback）

• MAX_SENDS_PER_ACCOUNT_PER_HOUR（デフォルト 60）

• MCP_ALLOWED_ORIGINS（カンマ区切り）

• MCP_ALLOWED_ORIGINS_HOSTS（カンマ区切り）

• PUBLIC_ADMIN_ALLOWED_ORIGINS（カンマ区切り）

最小限のブートストラップについては.env.exampleを参照してください。

Proton Bridgeのセットアップ

1. Proton Mail Bridgeをインストールします。

2. BridgeでProtonアカウントを追加し、生成されたIMAP/SMTP設定をコピーします。

3. その設定を使用してslab-emailを設定します：

   • POST /api/accounts/proton-bridge

4. テスト：

   • POST /api/accounts/:id/test

このプロジェクトは意図的にProtonログインの自動化を実装していません。Bridgeで生成された認証情報のみを使用してください。

docs/proton.mdを参照してください。

Gmailのセットアップ

1. Google Cloud OAuth認証情報を作成します。

2. .envにGOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_REDIRECT_URIを設定します。

3. サービスを起動します。

4. 使用：

   • POST /api/accounts/gmail/connectでauthorizationUrlを取得。

5. ブラウザでOAuthを完了します。

6. コールバック：

   • GET /api/oauth/google/callback

7. Gmailアカウントはリフレッシュトークンとともに暗号化されたDBに保存されます。

docs/gmail.mdを参照してください。

REST API

• ベース：

  • GET /health

  • /api/*

  • POST /mcp

• 認証：

  • 管理エンドポイント：Bearer <SLAB_EMAIL_ADMIN_KEY>

  • 運用 + MCP：Bearer <スコープ付きコネクタトークン>

完全なリクエスト/レスポンスの例についてはdocs/api.mdを参照してください。

MCP

エンドポイント：POST /mcp

ツール：

• email_list_accounts

• email_search

• email_get_message

• email_list_threads

• email_get_thread

• email_create_draft

• email_send

• email_reply

ツールのペイロードと使用法についてはdocs/mcp.mdを参照してください。

セキュリティモデル

• プロバイダーシークレットの暗号化/復号化にはSLAB_EMAIL_MASTER_KEYが必要です。

• シークレットは管理REST/MCPによって返されることはありません。

• スコープ付きコネクタトークンは、運用コンテキストで管理キーを置き換えます。

• 読み取り/書き込み/送信の権限はアクセスプロファイルごとに適用されます。

• 送信は(accountId, idempotencyKey)によって冪等です。

• 不明な送信結果はSEND_OUTCOME_UNKNOWNとして表面化され、決して盲目的に再試行されません。

• アカウントごとの送信スロットリングのデフォルト：MAX_SENDS_PER_ACCOUNT_PER_HOUR。

• ログは機密性の高いキーを難読化します。

データモデル

• email_accounts：アカウントメタデータとプロバイダー設定（シークレットなし）。

• email_account_secrets：暗号化されたペイロード（username、password、refreshToken）。

• access_profiles + access_profile_accounts。

• access_tokens：ハッシュ化されたコネクタトークン。

• send_operations：ステータス + 監査フィールドとidempotency_key。

docs/architecture.mdを参照してください。

Docker

• イメージビルド用のDockerfile。

• ローカル実行用のdocker-compose.yml。

注意：Proton Bridgeはローカルファーストです。Bridgeをホスト上のDocker外で実行する場合、コンテナはデフォルトでホストの127.0.0.1認証情報にアクセスできないため、接続性を慎重に設定してください（ホストネットワーキングまたは同等のもの）。

開発

npm run dev      # start with hot reload
npm test         # run test suite
npm run lint
npm run typecheck
npm run build
npm start        # run production bundle

テスト

ドメインテストの対象：

• アカウントライフサイクルとシークレット暗号化

• OAuth状態の検証

• プロファイルスコープと権限

• 検索/リストと取得ペイロードの分離

• 送信の冪等性

• 不明な送信結果の動作

• MCP認証/スコープ/ツール実行

制限事項（MVP）

• 添付ファイル未対応。

• メールボックス同期エンジン、ローカル全文検索インデックス、Webhookプッシュ同期なし。

• バッチ/アウトバウンドキャンペーンワークフローなし。

• このサービスにWebメールUIは含まれません。

slab-agents統合

../slab-agentsが存在する場合、統合契約と設定についてはdocs/slab-agents-integration.mdを参照してください。

ライセンス

MIT