# 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ỉ bind HTTP server cục bộ (mặc định `:8080`) |
| `CALLBACK_BASE_URL` | | Base URL public để tạo `callback_url` gửi OpenClaw (mặc định theo `LISTEN_ADDR`, ví dụ `http://localhost: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.