slab-email

Conector de correo electrónico sin interfaz gráfica para agentes de IA a través de REST y MCP.

slab-email es un microservicio local-first que estandariza el acceso al buzón detrás de una API normalizada y una superficie de herramientas MCP.

Está diseñado para slab-agents y otros entornos de ejecución de IA que necesitan acceso controlado a múltiples cuentas de correo electrónico con manejo seguro de credenciales.

¿Qué es?

slab-email no es una interfaz de usuario de correo electrónico.

Proporciona:

• Capacidades normalizadas de lectura/búsqueda/creación/envío sobre proveedores de correo electrónico.

• REST de administración para la gestión de cuentas y perfiles de acceso.

• Servidor MCP para clientes LLM/herramientas.

• Adaptadores a nivel de proveedor para:

  • Proton a través de Proton Mail Bridge (obligatorio).

  • IMAP/SMTP genérico.

  • Gmail a través de OAuth2 + API de Gmail.

• Almacenamiento de credenciales cifradas en SQLite.

• Tokens de conector con ámbito y capacidades por perfil.

• Idempotencia de envío y limitación de velocidad básica anti-bucle.

Arquitectura

Flujo de alto nivel:

• slab-agents llama a /mcp con un token de conector con ámbito.

• Los endpoints REST de administración configuran proveedores y perfiles de acceso.

• Las cuentas se almacenan en SQLite; las credenciales están cifradas en reposo.

• En el momento de la solicitud, se crean instancias de proveedor a partir de la configuración de la cuenta + el secreto descifrado.

• slab-email ejecuta operaciones contra las API del proveedor (IMAP/SMTP o API de Gmail).

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)

Características

• Soporte para múltiples cuentas:

  • conectar y gestionar múltiples cuentas simultáneamente.

• Abstracción de proveedor:

  • Proton Bridge + IMAP/SMTP genérico + Gmail.

• Permisos con ámbito de conector:

  • leer / borrador / enviar.

• Envío/respuesta idempotente con idempotencyKey.

• Cargas útiles de lectura/lista enhebradas e hidratación completa de mensajes.

• Secretos cifrados usando AES-256-GCM.

• Tokens de acceso con ámbito en perfiles.

• API de administración y API MCP separadas por requisitos de token.

• Listo para Docker y CI.

Pila tecnológica

• Node.js + TypeScript

• Express 5

• SQLite (better-sqlite3)

• Zod

• MCP SDK (@modelcontextprotocol/sdk)

• IMAP/SMTP: imapflow, nodemailer

• Gmail: googleapis / google-auth-library

Inicio rápido

1) Iniciar el servicio local

npm install
cp .env.example .env

Establece los valores en .env y ejecuta:

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

Esperado:

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

• /mcp disponible en POST /mcp.

2) Registrar un perfil con ámbito + token

Usa el token de administración para la gestión de cuentas/perfiles y el token de conector para el uso regular.

Configuración

Variables de entorno requeridas / relevantes:

• HOST (default 127.0.0.1)

• PORT (default 6981)

• DATABASE_PATH (default ./data/slab-email.db)

• SLAB_EMAIL_ADMIN_KEY (required)

• SLAB_EMAIL_MASTER_KEY (required, 32-byte key)

• GOOGLE_CLIENT_ID

• GOOGLE_CLIENT_SECRET

• GOOGLE_REDIRECT_URI (default http://127.0.0.1:6981/api/oauth/google/callback)

• MAX_SENDS_PER_ACCOUNT_PER_HOUR (default 60)

• MCP_ALLOWED_ORIGINS (comma-separated)

• MCP_ALLOWED_ORIGINS_HOSTS (comma-separated)

• PUBLIC_ADMIN_ALLOWED_ORIGINS (comma-separated)

Consulta .env.example para el arranque mínimo.

Configuración de Proton Bridge

1. Instala Proton Mail Bridge.

2. Añade tu cuenta de Proton en Bridge y copia la configuración IMAP/SMTP generada.

3. Configura slab-email con esa configuración a través de:

   • POST /api/accounts/proton-bridge

4. Prueba:

   • POST /api/accounts/:id/test

Este proyecto intencionalmente no implementa la automatización de inicio de sesión de Proton. Usa solo credenciales generadas por Bridge.

Consulta docs/proton.md.

Configuración de Gmail

1. Crea credenciales OAuth de Google Cloud.

2. Establece GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI en .env.

3. Inicia el servicio.

4. Usa:

   • POST /api/accounts/gmail/connect para obtener authorizationUrl.

5. Completa OAuth en el navegador.

6. Callback:

   • GET /api/oauth/google/callback

7. La cuenta de Gmail se almacena con el token de actualización en la base de datos cifrada.

Consulta docs/gmail.md.

API REST

• Base:

  • GET /health

  • /api/*

  • POST /mcp

• Autenticación:

  • Endpoints de administración: Bearer <SLAB_EMAIL_ADMIN_KEY>

  • Operacional + MCP: Bearer <token de conector con ámbito>

Consulta docs/api.md para ejemplos completos de solicitud/respuesta.

MCP

Endpoint: POST /mcp

Herramientas:

• email_list_accounts

• email_search

• email_get_message

• email_list_threads

• email_get_thread

• email_create_draft

• email_send

• email_reply

Consulta docs/mcp.md para cargas útiles y uso de las herramientas.

Modelo de seguridad

• SLAB_EMAIL_MASTER_KEY es necesario para cifrar/descifrar secretos de proveedores.

• Los secretos nunca son devueltos por la REST de administración/MCP.

• Los tokens de conector con ámbito reemplazan la clave de administración en contextos operacionales.

• Los permisos de lectura/escritura/envío se aplican por perfil de acceso.

• El envío es idempotente por (accountId, idempotencyKey).

• Los resultados de envío desconocidos se muestran como SEND_OUTCOME_UNKNOWN y nunca se reintentan automáticamente a ciegas.

• Límite de envío por cuenta predeterminado: MAX_SENDS_PER_ACCOUNT_PER_HOUR.

• Los registros redactan claves probablemente sensibles.

Modelo de datos

• email_accounts: metadatos de cuenta y configuración del proveedor (sin secretos).

• email_account_secrets: carga útil cifrada (username, password, refreshToken).

• access_profiles + access_profile_accounts.

• access_tokens: tokens de conector con hash.

• send_operations: campos de estado + auditoría y idempotency_key.

Consulta docs/architecture.md.

Docker

• Dockerfile para la construcción de la imagen.

• docker-compose.yml para el tiempo de ejecución local.

Nota: Proton Bridge es local-first. Si ejecutas Bridge fuera de Docker en el host, configura la conectividad cuidadosamente (red del host o equivalente) porque el contenedor no puede asumir acceso a las credenciales del host 127.0.0.1 por defecto.

Desarrollo

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

Pruebas

Las pruebas de dominio cubren:

• Ciclo de vida de la cuenta y cifrado de secretos

• Validación del estado OAuth

• Ámbito de perfil y permisos

• Separación de carga útil de búsqueda/lista vs obtención

• Idempotencia de envío

• Comportamiento de resultado de envío desconocido

• Autenticación/ámbito/ejecución de herramientas MCP

Limitaciones (MVP)

• Sin soporte para archivos adjuntos.

• Sin motor de sincronización de buzón, índice de búsqueda de texto completo local o sincronización push por webhook.

• Sin flujos de trabajo de lotes/campañas salientes.

• Sin interfaz de webmail en este servicio.

Integración con slab-agents

Si existe ../slab-agents, usa docs/slab-agents-integration.md para el contrato de integración y configuración.

Licencia

MIT