slab-email

Headless email connector for AI agents via REST and MCP.

slab-email is a local-first microservice that standardizes mailbox access behind a normalized API and MCP tool surface.

It is designed for slab-agents and other AI runtimes that need controlled access to multiple email accounts with secure credentials handling.

What is it?

slab-email is not an email UI.

It provides:

• Normalized read/search/create/send capabilities over email providers.

• Admin REST for account and access-profile management.

• MCP server for LLM/tooling clients.

• Provider-level adapters for:

  • Proton via Proton Mail Bridge (mandatory).

  • Generic IMAP/SMTP.

  • Gmail via OAuth2 + Gmail API.

• Encrypted credential storage in SQLite.

• Scoped connector tokens with per-profile capabilities.

• Send idempotency and basic anti-loop rate limiting.

Architecture

High-level flow:

• slab-agents calls /mcp with a scoped connector token.

• REST admin endpoints configure providers and access profiles.

• Accounts are stored in SQLite; credentials are encrypted at rest.

• At request time, provider instances are created from account config + decrypted secret.

• slab-email executes operations against provider APIs (IMAP/SMTP or 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)

Features

• Multi-account support:

  • connect and manage multiple accounts simultaneously.

• Provider abstraction:

  • Proton Bridge + IMAP/SMTP generic + Gmail.

• Connector-scoped permissions:

  • read / draft / send.

• Idempotent send/reply with idempotencyKey.

• Threaded read/list payloads and full message hydration.

• Encrypted secrets using AES-256-GCM.

• Access tokens scoped to profiles.

• Admin API and MCP API separated by token requirements.

• Docker and CI ready.

Stack

• Node.js + TypeScript

• Express 5

• SQLite (better-sqlite3)

• Zod

• MCP SDK (@modelcontextprotocol/sdk)

• IMAP/SMTP: imapflow, nodemailer

• Gmail: googleapis / google-auth-library

Quickstart

1) Start local service

npm install
cp .env.example .env

Set values in .env and run:

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

Expected:

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

• /mcp available on POST /mcp.

2) Register a scoped profile + token

Use admin token for account/profile management and connector token for regular usage.

Configuration

Required / relevant environment variables:

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

See .env.example for the minimum bootstrap.

Proton Bridge setup

1. Install Proton Mail Bridge.

2. Add your Proton account in Bridge and copy generated IMAP/SMTP config.

3. Configure slab-email with that config through:

   • POST /api/accounts/proton-bridge

4. Test:

   • POST /api/accounts/:id/test

This project intentionally does not implement Proton login automation. Use only Bridge-generated credentials.

See docs/proton.md.

Gmail setup

1. Create Google Cloud OAuth credentials.

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

3. Start service.

4. Use:

   • POST /api/accounts/gmail/connect to obtain authorizationUrl.

5. Complete OAuth in browser.

6. Callback:

   • GET /api/oauth/google/callback

7. Gmail account is stored with refresh token in encrypted DB.

See docs/gmail.md.

REST API

• Base:

  • GET /health

  • /api/*

  • POST /mcp

• Authentication:

  • Admin endpoints: Bearer <SLAB_EMAIL_ADMIN_KEY>

  • Operational + MCP: Bearer <scoped connector token>

See docs/api.md for full request/response examples.

MCP

Endpoint: POST /mcp

Tools:

• email_list_accounts

• email_search

• email_get_message

• email_list_threads

• email_get_thread

• email_create_draft

• email_send

• email_reply

See docs/mcp.md for tool payloads and usage.

Security model

• SLAB_EMAIL_MASTER_KEY is required to encrypt/decrypt provider secrets.

• Secrets are never returned by admin REST/MCP.

• Scoped connector tokens replace admin key in operational contexts.

• Read/write/send permissions are enforced per access profile.

• Send is idempotent by (accountId, idempotencyKey).

• Unknown send outcomes are surfaced as SEND_OUTCOME_UNKNOWN and never auto-retried blindly.

• Per-account send throttling default: MAX_SENDS_PER_ACCOUNT_PER_HOUR.

• Logs redact likely sensitive keys.

Data model

• email_accounts: account metadata and provider config (without secrets).

• email_account_secrets: encrypted payload (username, password, refreshToken).

• access_profiles + access_profile_accounts.

• access_tokens: hashed connector tokens.

• send_operations: status + audit fields and idempotency_key.

See docs/architecture.md.

Docker

• Dockerfile for image build.

• docker-compose.yml for local runtime.

Note: Proton Bridge is local-first. If running Bridge outside Docker on host, configure connectivity carefully (host networking or equivalent) because the container cannot assume access to host 127.0.0.1 credentials by default.

Development

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

Testing

Domain tests cover:

• Account lifecycle and secret encryption

• OAuth state validation

• Profile scoping and permissions

• Search/list vs get payload separation

• Send idempotency

• Unknown send outcome behavior

• MCP auth/scoping/tool execution

Limitations (MVP)

• No attachments support.

• No mailbox sync engine, local full-text search index, or webhook push sync.

• No batching/outbound campaign workflows.

• No webmail UI in this service.

slab-agents integration

If ../slab-agents exists, use docs/slab-agents-integration.md for integration contract and configuration.

License

MIT