slab-email

REST 및 MCP를 통해 AI 에이전트를 위한 헤드리스 이메일 커넥터.

slab-email은 정규화된 API 및 MCP 도구 표면 뒤에서 사서함 액세스를 표준화하는 로컬 우선 마이크로서비스입니다.

보안 자격 증명 처리를 통해 여러 이메일 계정에 대한 제어된 액세스가 필요한 slab-agents 및 기타 AI 런타임을 위해 설계되었습니다.

무엇인가요?

slab-email은 이메일 UI가 아닙니다.

다음을 제공합니다:

• 이메일 제공업체에 대한 정규화된 읽기/검색/생성/전송 기능.

• 계정 및 액세스 프로필 관리를 위한 관리 REST.

• LLM/도구 클라이언트를 위한 MCP 서버.

• 제공업체 수준 어댑터:

  • Proton Mail Bridge를 통한 Proton (필수).

  • 일반 IMAP/SMTP.

  • OAuth2 + Gmail API를 통한 Gmail.

• 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 available on POST /mcp.

2) 범위 지정 프로필 + 토큰 등록

계정/프로필 관리에는 관리자 토큰을, 일반 사용에는 커넥터 토큰을 사용하세요.

구성

필수/관련 환경 변수:

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

최소 부트스트랩은 .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 to obtain authorizationUrl.

5. 브라우저에서 OAuth를 완료합니다.

6. 콜백:

   • GET /api/oauth/google/callback

7. Gmail 계정은 새로 고침 토큰과 함께 암호화된 DB에 저장됩니다.

docs/gmail.md를 참조하세요.

REST API

• 기본:

  • GET /health

  • /api/*

  • POST /mcp

• 인증:

  • Admin endpoints: Bearer <SLAB_EMAIL_ADMIN_KEY>

  • Operational + MCP: Bearer <scoped connector token>

전체 요청/응답 예제는 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는 로컬 우선입니다. 호스트의 Docker 외부에서 Bridge를 실행하는 경우, 컨테이너가 기본적으로 호스트 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)

• 첨부 파일 지원 없음.

• 사서함 동기화 엔진, 로컬 전체 텍스트 검색 인덱스 또는 웹훅 푸시 동기화 없음.

• 배치/발신 캠페인 워크플로우 없음.

• 이 서비스에는 웹메일 UI가 없습니다.

slab-agents 통합

../slab-agents가 존재하는 경우, 통합 계약 및 구성을 위해 docs/slab-agents-integration.md를 사용하세요.

라이선스

MIT