slab-email

Headlesser E-Mail-Connector für KI-Agenten über REST und MCP.

slab-email ist ein lokaler Microservice, der den Mailbox-Zugriff hinter einer normalisierten API und MCP-Tool-Oberfläche standardisiert.

Es ist für slab-agents und andere KI-Laufzeiten konzipiert, die kontrollierten Zugriff auf mehrere E-Mail-Konten mit sicherer Verwaltung von Anmeldedaten benötigen.

Was ist das?

slab-email ist keine E-Mail-Benutzeroberfläche.

Es bietet:

• Normalisierte Lese-/Such-/Erstellungs-/Sende-Funktionen über E-Mail-Anbieter hinweg.

• Admin-REST für die Verwaltung von Konten und Zugriffsprofilen.

• MCP-Server für LLM-/Tooling-Clients.

• Anbieter-spezifische Adapter für:

  • Proton über Proton Mail Bridge (obligatorisch).

  • Generisches IMAP/SMTP.

  • Gmail über OAuth2 + Gmail API.

• Verschlüsselte Speicherung von Anmeldedaten in SQLite.

• Bereichsbezogene Connector-Tokens mit Berechtigungen pro Profil.

• Sende-Idempotenz und grundlegende Anti-Loop-Ratenbegrenzung.

Related MCP server: Mailport

Architektur

Ablauf auf hoher Ebene:

• slab-agents ruft /mcp mit einem bereichsbezogenen Connector-Token auf.

• REST-Admin-Endpunkte konfigurieren Anbieter und Zugriffsprofile.

• Konten werden in SQLite gespeichert; Anmeldedaten werden im Ruhezustand verschlüsselt.

• Zur Anfragezeit werden Anbieterinstanzen aus der Kontokonfiguration und dem entschlüsselten Geheimnis erstellt.

• slab-email führt Operationen gegen die Anbieter-APIs (IMAP/SMTP oder Gmail API) aus.

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)

Funktionen

• Multi-Konto-Unterstützung:

  • mehrere Konten gleichzeitig verbinden und verwalten.

• Anbieterabstraktion:

  • Proton Bridge + IMAP/SMTP generisch + Gmail.

• Connector-bezogene Berechtigungen:

  • lesen / entwerfen / senden.

• Idempotentes Senden/Antworten mit idempotencyKey.

• Thread-bezogene Lese-/Listen-Payloads und vollständige Nachrichten-Hydrierung.

• Verschlüsselte Geheimnisse mit AES-256-GCM.

• Zugriffstokens, die auf Profile beschränkt sind.

• Admin-API und MCP-API getrennt durch Token-Anforderungen.

• Docker- und CI-bereit.

Technologie-Stack

• Node.js + TypeScript

• Express 5

• SQLite (better-sqlite3)

• Zod

• MCP SDK (@modelcontextprotocol/sdk)

• IMAP/SMTP: imapflow, nodemailer

• Gmail: googleapis / google-auth-library

Schnellstart

1) Lokalen Dienst starten

npm install
cp .env.example .env

Werte in .env setzen und ausführen:

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

Erwartet:

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

• /mcp verfügbar unter POST /mcp.

2) Ein bereichsbezogenes Profil + Token registrieren

Admin-Token für die Konto-/Profilverwaltung und Connector-Token für die reguläre Nutzung verwenden.

Konfiguration

Erforderliche / relevante Umgebungsvariablen:

• HOST (Standard 127.0.0.1)

• PORT (Standard 6981)

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

• SLAB_EMAIL_ADMIN_KEY (erforderlich)

• SLAB_EMAIL_MASTER_KEY (erforderlich, 32-Byte-Schlüssel)

• GOOGLE_CLIENT_ID

• GOOGLE_CLIENT_SECRET

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

• MAX_SENDS_PER_ACCOUNT_PER_HOUR (Standard 60)

• MCP_ALLOWED_ORIGINS (kommagetrennt)

• MCP_ALLOWED_ORIGINS_HOSTS (kommagetrennt)

• PUBLIC_ADMIN_ALLOWED_ORIGINS (kommagetrennt)

Siehe .env.example für die minimale Bootstrap-Konfiguration.

Proton Bridge Einrichtung

1. Proton Mail Bridge installieren.

2. Proton-Konto in Bridge hinzufügen und generierte IMAP/SMTP-Konfiguration kopieren.

3. slab-email mit dieser Konfiguration konfigurieren über:

   • POST /api/accounts/proton-bridge

4. Testen:

   • POST /api/accounts/:id/test

Dieses Projekt implementiert bewusst keine Proton-Login-Automatisierung. Verwenden Sie nur Bridge-generierte Anmeldedaten.

Siehe docs/proton.md.

Gmail Einrichtung

1. Google Cloud OAuth-Anmeldedaten erstellen.

2. GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI in .env setzen.

3. Dienst starten.

4. Verwenden:

   • POST /api/accounts/gmail/connect um authorizationUrl zu erhalten.

5. OAuth im Browser abschließen.

6. Callback:

   • GET /api/oauth/google/callback

7. Gmail-Konto wird mit Refresh-Token in der verschlüsselten Datenbank gespeichert.

Siehe docs/gmail.md.

REST API

• Basis:

  • GET /health

  • /api/*

  • POST /mcp

• Authentifizierung:

  • Admin-Endpunkte: Bearer <SLAB_EMAIL_ADMIN_KEY>

  • Operativ + MCP: Bearer <bereichsbezogenes Connector-Token>

Siehe docs/api.md für vollständige Anfrage-/Antwortbeispiele.

MCP

Endpunkt: POST /mcp

Tools:

• email_list_accounts

• email_search

• email_get_message

• email_list_threads

• email_get_thread

• email_create_draft

• email_send

• email_reply

Siehe docs/mcp.md für Tool-Payloads und Nutzung.

Sicherheitsmodell

• SLAB_EMAIL_MASTER_KEY ist erforderlich, um Anbietergeheimnisse zu verschlüsseln/entschlüsseln.

• Geheimnisse werden niemals von Admin-REST/MCP zurückgegeben.

• Bereichsbezogene Connector-Tokens ersetzen den Admin-Schlüssel in operativen Kontexten.

• Lese-/Schreib-/Sendeberechtigungen werden pro Zugriffsprofil durchgesetzt.

• Senden ist idempotent durch (accountId, idempotencyKey).

• Unbekannte Sendeergebnisse werden als SEND_OUTCOME_UNKNOWN gemeldet und niemals blind wiederholt.

• Standardmäßige Sende-Drosselung pro Konto: MAX_SENDS_PER_ACCOUNT_PER_HOUR.

• Protokolle schwärzen wahrscheinlich sensible Schlüssel.

Datenmodell

• email_accounts: Kontometadaten und Anbieterkonfiguration (ohne Geheimnisse).

• email_account_secrets: verschlüsselte Payload (username, password, refreshToken).

• access_profiles + access_profile_accounts.

• access_tokens: gehashte Connector-Tokens.

• send_operations: Status + Prüffelder und idempotency_key.

Siehe docs/architecture.md.

Docker

• Dockerfile für Image-Erstellung.

• docker-compose.yml für lokale Laufzeit.

Hinweis: Proton Bridge ist lokal-first. Wenn Bridge außerhalb von Docker auf dem Host ausgeführt wird, muss die Konnektivität sorgfältig konfiguriert werden (Host-Netzwerk oder Äquivalent), da der Container standardmäßig keinen Zugriff auf die Host-127.0.0.1-Anmeldedaten annehmen kann.

Entwicklung

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

Tests

Domänentests decken ab:

• Konto-Lebenszyklus und Geheimnisverschlüsselung

• OAuth-Statusvalidierung

• Profilbereich und Berechtigungen

• Trennung von Suche/Liste vs. Get-Payload

• Sende-Idempotenz

• Verhalten bei unbekanntem Sendeergebnis

• MCP-Auth/Bereich/Tool-Ausführung

Einschränkungen (MVP)

• Keine Anhangsunterstützung.

• Keine Mailbox-Synchronisierungs-Engine, lokaler Volltextsuchindex oder Webhook-Push-Synchronisation.

• Keine Batch-/Ausgehende-Kampagnen-Workflows.

• Keine Webmail-Benutzeroberfläche in diesem Dienst.

slab-agents Integration

Wenn ../slab-agents existiert, verwenden Sie docs/slab-agents-integration.md für den Integrationsvertrag und die Konfiguration.

Lizenz

MIT