Hướng dẫn thao tác cho AI agent

MONA Mail là dịch vụ gửi email giao dịch cho phần mềm và AI agent của người Việt qua một API, không cần thẻ, thuộc nhóm MONA Cloud của The MONA Group. Chi tiết từng endpoint nằm ở tài liệu API; schema ở OpenAPI; base URL https://api.monamail.vn/v1.

Phạm vi và thứ tự gọi tool

Hướng dẫn này dành cho AI làm việc trong repository của bạn, sau khi bạn đăng nhập MONA Pass. AI hoàn thành tích hợp qua MCP hoặc API; không bắt bạn mở dashboard để tạo key hay webhook.

Transactional API mở beta 09/2026; hộp thư cho AI agent chạy thật từ 16/09/2026 (xem cách dùng hộp thư); email marketing mở ở giai đoạn sau. AI không gọi Broadcasts vì chưa có trong contract.

1. Đọc tài liệu API (bản Markdown /docs.md), OpenAPI và danh sách tool thực tế. Đăng nhập bằng npx -y monacloud-mcp login theo device flow; người dùng tự duyệt đăng nhập MONA Pass.
2. mail_account, mail_plans: đọc email chủ, quota, domain và next_step. Không tạo tài khoản riêng. JWT phải có audience monamail hoặc mona-products.
3. mail_send từ [email protected] tới email chủ với sandbox:true. Giữ idempotency_key theo tác vụ; mail_status phải trả sandbox, đọc sandbox_preview.
4. mail_domain_add trả 3 record TXT. DKIM đúng là đủ; gộp vào SPF hiện có, DMARC chỉ cảnh báo. Chỉ dùng mail_domain_cloudflare khi có token được cấp cho đúng zone; chưa có quyền thì đưa nguyên records[] cho người dùng thêm DNS.
5. mail_domain_verify: đọc checks, chờ DNS lan truyền rồi thử lại có giới hạn. Không tự bỏ qua domain_not_verified.
6. mail_api_key_create với JWT: tạo key test hoặc live theo phạm vi đã được giao. Ghi key vào .env của app hoặc secret store, giữ .env trong .gitignore. Key không xuất hiện trong chat, log, commit, ảnh chụp hay history.
7. Tích hợp SDK và gửi OTP thử thật tới địa chỉ đã được cho phép. Theo dõi mail_status tới delivered; queued và sent chưa chứng minh MX đích đã nhận. Không tuyên bố mail đã tới hộp thư người nhận hay người nhận đã đọc.
8. mail_webhook_create, mail_webhook_test: lưu secret, kiểm HMAC trên raw bytes và độ lệch 300 giây. Xử lý idempotent theo event id; ghi DB bền vững rồi mới trả 2xx.
9. Thử bounce tới địa chỉ QC được phép; đọc mail_status, mail_suppressions_list và thống kê bounce. Kiểm hard bounce đã có suppression; không gỡ lớp chặn toàn hệ.
10. Báo kết quả: email_id, trạng thái thật, domain và checks, kết quả webhook test và request_id của lỗi. Ghi rõ bước nào chưa xác minh được.

Cách AI dùng hộp thư agent để nhận OTP và trả lời khách

Khi cần một địa chỉ email để trực việc, AI tạo hộp thư agent rồi nhận mã OTP giúp người dùng hoặc trả lời khách trong cùng luồng thư. Hộp thư chạy thật từ 16/09/2026; endpoint tương ứng ở tài liệu API.

1. Tạo hộp: gọi mail_inbox_create với agent_id gồm chữ thường, chữ số, ., _, -, tối đa 64 ký tự.
2. Chờ hoặc liệt kê thư: chờ OTP hay nội dung cụ thể thì gọi mail_inbox_wait với match=otp hoặc regex tối đa 200 ký tự, timeout từ 0 đến 300 giây; có thư khớp thì lấy mã ở extracted_code, hết giờ thì báo lại chứ không đoán mã. Cần xem danh sách thì gọi mail_inbox_messages.
3. Đọc thư: gọi mail_inbox_message với ID thư; lần đọc đầu tự đánh dấu seen=true.
4. Trả lời khi được giao: gọi mail_inbox_reply để gửi trong cùng luồng; mỗi thư trả lời tính vào hạn mức gửi trong tháng.
5. Dọn dẹp: xong việc hoặc không dùng nữa thì gọi mail_inbox_delete để xoá mềm.

• Địa chỉ: không truyền domain thì hộp là <agent_id>@<slug tài khoản>.agent.monamail.vn; có domain đã xác minh thì <agent_id>@<domain>.
• Số hộp theo gói: Miễn phí 1, Khởi nghiệp 5, Kinh doanh 25, Doanh nghiệp 100. Thư đến lưu tối đa 90 ngày.

Xong việc, AI báo lại ID và địa chỉ đầy đủ của hộp, trạng thái thư (đã nhận hay chưa), mã extracted_code nếu dùng chờ OTP, và nhắc người dùng xác minh domain nếu muốn hộp nằm trên tên miền riêng.

Prompt tổng để giao việc cho AI

Dán prompt này vào Claude Code, Codex, Gemini CLI hoặc Cursor sau khi đã cài MCP. Prompt không chứa secret.

Đọc https://monamail.vn/agent-guide.md và danh sách tool monacloud-mcp sau khi tôi đăng nhập MONA Pass.
Gọi mail_account; gửi thử [email protected] tới email chủ, dùng sandbox trước và key chống trùng ổn định.
Gọi mail_domain_add shop-test.monamail-qc.vn; xin thêm DNS hoặc dùng mail_domain_cloudflare khi đã có token cho đúng zone, rồi mail_domain_verify.
Gọi mail_api_key_create, lưu MONAMAIL_API_KEY trong .env của app; không in key ra chat; thêm SDK và code gửi OTP.
Gửi thử thật trong phạm vi đã được yêu cầu; dùng mail_status tới delivered, không coi queued hoặc sandbox là đã tới hộp thư.
Gọi mail_webhook_create và mail_webhook_test; thử bounce bằng địa chỉ QC đã được cho phép, kiểm mail_status và mail_suppressions_list.
Dừng khi cần đăng nhập, thêm DNS ngoài quyền đang có hoặc nạp tiền; báo bước kế và request_id khi lỗi; không mở dashboard để cấu hình thay API.

Khi nào AI dừng để người dùng tự làm?

• Tài khoản: đăng ký, đăng nhập MONA Pass hoặc duyệt device flow là việc của người dùng. AI không xin mật khẩu, không tự xử lý OTP hay KYC thay người.
• DNS: chưa có quyền quản lý zone thì AI đưa records[] cần thêm và tiếp tục sau khi người dùng làm xong. Có token Cloudflare đúng quyền trong phạm vi được giao thì AI tự gọi API.
• Tiền: ví thiếu hoặc vượt ngân sách thì AI báo needed_vnd/topup_hint khi API có trả, và dùng cloud_topup để người dùng nạp qua VietQR. AI không tự thanh toán, không tự tăng ngân sách.
• Thao tác có hậu quả: gửi thật, đổi gói, thu hồi key và xoá tài nguyên làm theo phạm vi người dùng đã giao. Đã được cho phép thì không hỏi lại; nằm ngoài phạm vi thì trình bày cụ thể tác vụ cần người dùng đồng ý.

Sandbox và bảo vệ secret

Key mm_test_ không gửi ra Internet, không trừ ví, không tính quota. Trong MCP, sandbox:true tương đương header X-Mona-Sandbox: 1. AI chỉ test bằng tool hiện có, không giả lập kết quả production khi mạng lỗi.

API key được tạo và xoay qua API; sau khi rotate, key cũ còn dùng được 24 giờ rồi bị revoke. Webhook secret xoay bằng endpoint rotate. Khi nghi lộ key, AI thu hồi hoặc xoay key trong phạm vi sự cố đã được giao.

Idempotency và khôi phục lỗi

Mọi POST ghi dữ liệu có Idempotency-Key ổn định trong 24 giờ. Cùng key phải đi cùng body; tác vụ mới với body khác thì đổi key. SDK retry một lần cho 429/5xx, không retry vô hạn.

AI không đánh dấu hoàn tất nếu bước gửi thật, bounce hoặc webhook chưa chạy được. Bảng mã lỗi đầy đủ ở tài liệu API.

Giới hạn gửi và thời gian lưu dữ liệu

• 600 request/phút/account; domain mới 500 mail/ngày trong tuần đầu.
• 1 đến 50 người nhận mỗi email, 100 email mỗi batch.
• Đính kèm tối đa 10 MB, hẹn giờ gửi tối đa 7 ngày.
• Nội dung lưu 30 ngày, metadata 1 năm, đính kèm tối đa 7 ngày.

Không dùng lịch sử mail làm kho dữ liệu nghiệp vụ dài hạn. Hỗ trợ: tổng đài 1900 636 648, [email protected]. Báo lỗi bảo mật: [email protected].

Cài MCP cho Claude Code, Codex, Gemini CLI và Cursor

claude mcp add monacloud -- npx -y monacloud-mcp
npx -y monacloud-mcp login

Codex dùng cấu hình MCP command=npx, args=["-y", "monacloud-mcp"]; xem cấu hình cụ thể ở trang gửi mail bằng AI agent. Gemini CLI cài bằng gemini mcp add monacloud -- npx -y monacloud-mcp. Cursor dùng cùng command và args trong mcpServers.

MONA Mail do The MONA Group phát triển, công ty phần mềm và hạ tầng Việt Nam từ 2016, hơn 14.000 dự án, 85% khách ở lại. MONA Pay và MONA Pass đang dùng MONA Mail để gửi email giao dịch từ 09/2026.