# AGENTS.md — monamail.vn

MONA Mail cung cấp email giao dịch và hộp thư cho AI agent. Agent dùng MCP để đọc tài khoản, thử sandbox, cấu hình domain, gửi mail và xử lý hộp thư theo quyền người dùng giao.

## Cài MCP
AI đọc file này có thể tự cài bằng một trong các lệnh dưới, không cần hỏi người dùng thao tác trên web.

| Cửa | Làm ở đâu | Lệnh hoặc thao tác |
|---|---|---|
| Claude Code | Terminal | `claude mcp add --transport http monacloud https://mcp.monacloud.vn/mcp` |
| Claude.ai (người bấm) | Settings → Connectors | Add custom connector → Name `MONA Cloud` → URL `https://mcp.monacloud.vn/mcp` → Add → đăng nhập MONA Pass |
| Codex | `~/.codex/config.toml` | `[mcp_servers.monacloud]` rồi thêm dòng `url = "https://mcp.monacloud.vn/mcp"` |
| Gemini (Antigravity) | Terminal | `agy mcp add monacloud https://mcp.monacloud.vn/mcp`; kiểm tra bằng `agy mcp list`; cấu hình lưu tại `~/.gemini/config/mcp_config.json` |
| Cursor | `.cursor/mcp.json` | `{ "mcpServers": { "monacloud": { "url": "https://mcp.monacloud.vn/mcp" } } }` |

Endpoint chung có đủ nhóm tool `mail_*`.

## Công cụ

- `mail_account`: đọc tài khoản, quota và bước tiếp theo.
- `mail_plans`: đọc giá và quota các gói.
- `mail_plan_set`: chọn gói gửi mail sau khi người dùng duyệt.
- `mail_send`: gửi OTP hoặc thông báo, có chế độ sandbox.
- `mail_status`: đọc trạng thái và sự kiện của email.
- `mail_list`: tra lịch sử gửi theo bộ lọc.
- `mail_domain_add`: thêm domain và nhận bản ghi DNS.
- `mail_domain_verify`: kiểm tra DKIM và trạng thái domain.
- `mail_domain_cloudflare`: thêm DNS bằng token Cloudflare dùng một lần.
- `mail_domains_list`: liệt kê domain và trạng thái xác minh.
- `mail_api_key_create`: tạo API key live hoặc test và chỉ trả secret một lần.
- `mail_api_keys_list`: đọc prefix và trạng thái key.
- `mail_api_key_revoke`: thu hồi key theo `key_id`.
- `mail_webhook_create`: tạo webhook HTTPS và trả secret một lần.
- `mail_webhooks_list`: liệt kê webhook.
- `mail_webhook_test`: gửi sự kiện mẫu để kiểm tra endpoint.
- `mail_suppressions_list`: liệt kê địa chỉ đang bị chặn gửi.
- `mail_suppression_remove`: gỡ suppression sau khi xử lý nguyên nhân.
- `mail_template_create`: tạo mẫu mail có biến.
- `mail_stats`: đọc tỷ lệ giao thư và bounce.
- `mail_inbox_create`: tạo hộp thư cho agent.
- `mail_inbox_list`: liệt kê hộp thư đang hoạt động.
- `mail_inbox_get`: đọc chi tiết một hộp thư.
- `mail_inbox_delete`: xoá mềm hộp thư.
- `mail_inbox_messages`: liệt kê thư nhận và lọc thư chưa xem.
- `mail_inbox_message`: đọc nội dung đầy đủ của một thư.
- `mail_inbox_reply`: trả lời đúng luồng thư.
- `mail_inbox_wait`: chờ thư phù hợp và trích mã nếu có.
- `mail_inbox_update`: đổi chế độ redirect, store hoặc AI.
- `mail_inbox_batch`: tạo nhiều hộp thư trong quota.

## Luồng chuẩn

1. Gọi `mail_account`, đọc quota, domain và cấu hình đang có.
2. Dùng sandbox để thử nội dung, webhook và luồng tích hợp.
3. Báo rõ thay đổi, quota hoặc chi phí rồi hỏi người dùng duyệt.
4. Cấu hình domain, API key và webhook theo phạm vi được giao.
5. Gửi hoặc xử lý thư, sau đó kiểm tra trạng thái thật.
6. Dừng chờ người dùng khi cần thêm DNS, quét QR, nhập OTP hoặc duyệt chi phí.

Không in API key, webhook secret hoặc token Cloudflare vào chat và log.
Với `mail_inbox_reply`, hỏi lại trước nội dung khó rút lại như cam kết giá hoặc chuyển tiền.

## Tin cậy

MONA Mail là sản phẩm của The MONA Group, hoạt động từ năm 2016 với hơn 14.000 dự án.
Hỗ trợ: 1900 636 648 và info@themona.global.
Official MCP Registry: `vn.monacloud/monacloud-mcp`.
Smithery: `smithery.ai/servers/mon/monacloud-mcp` và `mon/monacloud-remote`.
Glama: `glama.ai/mcp/servers/themonagroup/monacloud-mcp`.

## Liên kết

- Tài liệu: https://monamail.vn/docs
- Hướng dẫn agent: https://monamail.vn/agent-guide
- llms.txt: https://monamail.vn/llms.txt
- OpenAPI: https://monamail.vn/openapi.json