slab-email

Безголовый коннектор электронной почты для AI-агентов через REST и MCP.

slab-email — это локальный микросервис, который стандартизирует доступ к почтовым ящикам через нормализованный API и поверхность инструментов MCP.

Он предназначен для slab-agents и других сред выполнения ИИ, которым требуется контролируемый доступ к нескольким учетным записям электронной почты с безопасной обработкой учетных данных.

Что это такое?

slab-email — это не интерфейс электронной почты.

Он предоставляет:

• Нормализованные возможности чтения/поиска/создания/отправки через почтовых провайдеров.

• Admin REST для управления учетными записями и профилями доступа.

• MCP-сервер для LLM/инструментальных клиентов.

• Адаптеры на уровне провайдеров для:

  • 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.

• Токены доступа с ограничением по профилям.

• Admin 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. Добавьте свою учетную запись Proton в Bridge и скопируйте сгенерированную конфигурацию IMAP/SMTP.

3. Настройте slab-email с этой конфигурацией через:

   • POST /api/accounts/proton-bridge

4. Проверьте:

   • POST /api/accounts/:id/test

Этот проект намеренно не реализует автоматизацию входа в Proton. Используйте только учетные данные, сгенерированные Bridge.

Смотрите docs/proton.md.

Настройка Gmail

1. Создайте учетные данные OAuth в Google Cloud.

2. Установите GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI в .env.

3. Запустите сервис.

4. Используйте:

   • POST /api/accounts/gmail/connect для получения authorizationUrl.

5. Завершите OAuth в браузере.

6. Обратный вызов:

   • GET /api/oauth/google/callback

7. Учетная запись Gmail сохраняется с токеном обновления в зашифрованной БД.

Смотрите 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 требуется для шифрования/расшифровки секретов провайдера.

• Секреты никогда не возвращаются через admin 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)

• Нет поддержки вложений.

• Нет механизма синхронизации почтовых ящиков, локального полнотекстового поискового индекса или вебхуковой push-синхронизации.

• Нет пакетной обработки/кампаний исходящих писем.

• Нет веб-интерфейса почты в этом сервисе.

Интеграция с slab-agents

Если существует ../slab-agents, используйте docs/slab-agents-integration.md для контракта интеграции и конфигурации.

Лицензия

MIT