# Email-OpenClaw Bridge

Bridge tự động xử lý email bằng OpenClaw AI theo luồng:

```text
Ingress (IMAP) → Safety Checks → External Rules → Dispatch (OpenClaw) → Callback → Egress (SMTP reply)
```

README này tập trung vào onboarding và vận hành cơ bản. Chi tiết kỹ thuật hiện hành được tách sang `docs/architecture/overview.md`.

## Tính năng chính

- Theo dõi mailbox realtime bằng IMAP IDLE
- Giữ thread email qua `In-Reply-To` và `References`
- Chống duplicate theo `message_id`
- Chặn anti-loop và hỗ trợ whitelist/blocklist
- Gửi callback vào bridge rồi phản hồi lại qua SMTP
- Lưu trạng thái pipeline bằng SQLite để không mất tiến trình khi restart

## Yêu cầu tối thiểu

- Go 1.23+
- Docker và Docker Compose nếu chạy bằng container

## 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

```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 là `993` |
| `IMAP_USER` | ✅ | IMAP username |
| `IMAP_PASS` | ✅ | IMAP password |
| `SMTP_HOST` | ✅ | SMTP server hostname |
| `SMTP_PORT` | ✅ | SMTP port, thường là `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 bridge, dùng cho anti-loop |
| `WHITELIST_EMAILS` | | Danh sách email được phép, phân cách bằng dấu phẩy |
| `BLOCKLIST_EMAILS` | | Danh sách email bị chặn, phân cách bằng dấu phẩy |
| `IMAP_PROXY_URL` | | Proxy cho IMAP, hỗ trợ `socks5://`, `http://`, `https://` |
| `LISTEN_ADDR` | | Địa chỉ bind HTTP server, mặc định `:8080` |
| `CALLBACK_BASE_URL` | | Base URL public để tạo `callback_url`, mặc định suy ra từ `LISTEN_ADDR` |

## Health checks

| Endpoint | Mục đích |
|---|---|
| `GET /healthz` | Liveness check, xác nhận process còn sống |
| `GET /readyz` | Readiness check, xác nhận DB writable và config bắt buộc hợp lệ |

## Đọc thêm

- [Technical overview](docs/architecture/overview.md)
- [Architecture Decision Records](docs/adr/README.md)

## License

Private — internal use only.