Email Client Service (cbemail)¶

Status: Active URL: https://pobox.nominate.ai Port: 32212

Overview¶

cbemail is a headless email client API service that allows external clients to manage IMAP/SMTP mailboxes via REST API. No user management - clients register with email credentials and receive a session ID for subsequent operations.

Architecture¶

Client App → cbemail API → IMAP/SMTP Server
                ↓
           DuckDB (sessions, credentials, message cache)

Authentication Model¶

Client calls POST /api/sessions with email credentials
API validates credentials by testing IMAP/SMTP connections
Returns JWT token with session_id embedded
Subsequent calls use Bearer token or X-API-Key header

API Endpoints¶

Session Management¶

Method	Endpoint	Description
POST	`/api/sessions`	Create session (register credentials)
GET	`/api/sessions/{id}`	Get session info
DELETE	`/api/sessions/{id}`	Revoke session
GET	`/api/sessions/{id}/health`	Test IMAP/SMTP connectivity

IMAP Operations¶

Method	Endpoint	Description
GET	`/api/mailbox/folders`	List folders
POST	`/api/mailbox/folders`	Create folder
DELETE	`/api/mailbox/folders/{name}`	Delete folder
GET	`/api/mailbox/messages`	List messages
GET	`/api/mailbox/messages/{uid}`	Get single message
DELETE	`/api/mailbox/messages/{uid}`	Delete message
POST	`/api/mailbox/messages/{uid}/move`	Move to folder
POST	`/api/mailbox/messages/{uid}/mark`	Mark read/unread/flagged

SMTP Operations¶

Method	Endpoint	Description
POST	`/api/send`	Send email
POST	`/api/send/batch`	Send multiple emails

Quick Start¶

# Install dependencies
pip install -r requirements.txt

# Run development server
uvicorn src.api.main:app --reload --host 0.0.0.0 --port 32212

# Or use the run script
./run.sh

Configuration¶

Environment variables (.env):

Variable	Description
`HOST`	Server host (default: 0.0.0.0)
`PORT`	Server port (default: 32212)
`DB_PATH`	DuckDB path (default: db/cbemail.duckdb)
`SECRET_KEY`	JWT and credential encryption key
`ACCESS_TOKEN_EXPIRE_MINUTES`	Token expiry (default: 30)
`API_KEYS`	Comma-separated API keys for service auth
`LOG_LEVEL`	Logging level (default: INFO)

Key Features¶

Credentials Encryption - Passwords encrypted at rest using Fernet
Provider Detection - Auto-detects IMAP/SMTP servers from email domain
Stateless Connections - IMAP/SMTP connections created on-demand
Embedded Database - DuckDB for lightweight storage

Example Usage¶

# Create session
curl -X POST localhost:32212/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"email": "test@gmail.com", "password": "app-password"}'

# List messages
curl "localhost:32212/api/mailbox/messages?folder=INBOX&limit=10" \
  -H "Authorization: Bearer {token}"

# Send email
curl -X POST localhost:32212/api/send \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"to": "recipient@example.com", "subject": "Test", "body": "Hello"}'

Deployment¶

Systemd Service: systemd/cbemail.service
SSL: Wildcard certificate via NGINX
PIN Gate: Enabled for authentication