Initial commit: email-openclaw bridge v1

Full pipeline: IMAP ingress -> OpenClaw dispatch -> callback -> SMTP reply.
SQLite stateful storage with idempotency, threading, and retry logic.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

README.md

@@ -0,0 +1,105 @@
+# Email-OpenClaw Bridge
+
+Tự động xử lý email bằng OpenClaw AI theo luồng:
+
+```
+Ingress (IMAP) → Dispatch (OpenClaw) → Callback → Egress (SMTP reply)
+```
+
+## Tính năng
+
+- **IMAP IDLE** — theo dõi mailbox realtime, nhận email mới tức thì
+- **Threading** — giữ nguyên email thread qua `In-Reply-To` / `References`
+- **Idempotency** — chống duplicate theo `message_id`
+- **Anti-loop & Whitelist** — bỏ qua email từ chính hệ thống, chỉ xử lý sender được phép
+- **Retry** — tối đa 3 lần với backoff 1s → 5s → 15s cho cả OpenClaw và SMTP
+- **Stateful** — SQLite lưu trạng thái pipeline, không mất dữ liệu khi restart
+
+## Kiến trúc
+
+```
+cmd/bridge/main.go           Entrypoint
+internal/
+├── config/                   Đọc cấu hình từ .env
+├── database/                 SQLite + GORM, auto-migrate
+├── logging/                  Structured JSON logging (slog)
+├── api/                      HTTP server (Gin): health checks, webhook callback
+├── mail/                     IMAP ingress + SMTP egress
+└── ai_client/                OpenClaw HTTP dispatch
+```
+
+## Yêu cầu
+
+- Go 1.23+
+- Docker & Docker Compose (cho deploy)
+
+## Quickstart
+
+### 1. Cấu hình
+
+```bash
+cp .env.example .env
+# Sửa .env với thông tin IMAP/SMTP/OpenClaw thực tế
+```
+
+### 2. Chạy local (development)
+
+```bash
+go run ./cmd/bridge
+```
+
+### 3. Chạy bằng Docker
+
+```bash
+docker compose up -d
+docker logs -f claw-email-bridge
+```
+
+## Cấu hình (.env)
+
+| Biến | Bắt buộc | Mô tả |
+|---|:---:|---|
+| `IMAP_HOST` | ✅ | IMAP server hostname |
+| `IMAP_PORT` | ✅ | IMAP port (thường `993`) |
+| `IMAP_USER` | ✅ | IMAP username |
+| `IMAP_PASS` | ✅ | IMAP password |
+| `SMTP_HOST` | ✅ | SMTP server hostname |
+| `SMTP_PORT` | ✅ | SMTP port (thường `587`) |
+| `SMTP_USER` | ✅ | SMTP username |
+| `SMTP_PASS` | ✅ | SMTP password |
+| `OPENCLAW_URL` | ✅ | OpenClaw API endpoint |
+| `OPENCLAW_API_KEY` | | OpenClaw API key (nếu cần) |
+| `BRIDGE_CALLBACK_TOKEN` | ✅ | Token xác thực webhook callback |
+| `SYSTEM_EMAIL` | ✅ | Email của hệ thống (dùng cho anti-loop) |
+| `WHITELIST_EMAILS` | | Danh sách email được phép, phân cách bằng dấu phẩy |
+| `IMAP_PROXY_URL` | | SOCKS5 proxy cho IMAP (vd: `socks5://user:pass@host:port`) |
+| `LISTEN_ADDR` | | Địa chỉ HTTP server (mặc định `:8080`) |
+
+## Health Checks
+
+| Endpoint | Mục đích |
+|---|---|
+| `GET /healthz` | Liveness — process còn sống |
+| `GET /readyz` | Readiness — DB writable + config hợp lệ |
+
+## Pipeline trạng thái
+
+```
+RECEIVED → AI_PROCESSING → CALLBACK_DONE → COMPLETED
+    ↓           ↓                ↓
+ IGNORED      FAILED        SMTP_RETRYING → FAILED
+```
+
+## Công nghệ
+
+| Thành phần | Thư viện |
+|---|---|
+| HTTP Server | [gin-gonic/gin](https://github.com/gin-gonic/gin) |
+| Database | [GORM](https://gorm.io) + [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite) (pure Go, no CGO) |
+| IMAP | [emersion/go-imap](https://github.com/emersion/go-imap) |
+| Logging | [log/slog](https://pkg.go.dev/log/slog) (stdlib) |
+| Config | [joho/godotenv](https://github.com/joho/godotenv) |
+
+## License
+
+Private — internal use only.