npm install monamail
# MONAMAIL_API_KEY trong .env; dùng key mm_test_ để gửi thử miễn phí
node --input-type=module -e 'import {MonaMail} from "monamail"; await new MonaMail(process.env.MONAMAIL_API_KEY).emails.send({from:"[email protected]",to:process.env.MONAMAIL_OWNER_EMAIL,subject:"Thử mail",text:"Xin chào"})'

MONA Mail node 0.1.1

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: một API, trả VND qua ví MONA Cloud và nạp bằng VietQR, thuộc nhóm MONA Cloud của The MONA Group.

import { MonaMail, MonaMailError } from 'monamail';
const client = new MonaMail(process.env.MONAMAIL_API_KEY, { timeoutMs: 15000 });
const sent = await client.emails.send({ from: 'Shop <[email protected]>', to: '[email protected]', subject: 'OTP', text: '123456' }, { idempotencyKey: 'otp-request-123' });
await client.emails.get(sent.id);
await client.domains.create({ domain: 'shop.vn' });
// JWT MONA Pass cần cho tạo, xoay, thu hồi API key và đổi gói.
const valid = MonaMail.verifyWebhook({ secret: process.env.MONAMAIL_WEBHOOK_SECRET!, timestamp, body: rawBody, signature, now: Date.now() / 1000 });

Node ≥18; global fetch; không dependency runtime. CommonJS: const { MonaMail } = require('monamail'). Tuỳ chọn constructor: baseUrl, timeoutMs, fetch để mock. now dùng Unix giây; bỏ now chỉ kiểm chữ ký.

Bề mặt SDK

| Nhóm | Hàm | |---|---| | emails | send, get, list, cancel, batch, events | | domains | create, get, list, verify, remove, cloudflare | | apiKeys | list, create, rotate, revoke | | webhooks | create, list, test, rotate, remove, deliveries | | suppressions | list, add, remove | | templates | create, get, list, update, remove, render | | account | get, setPlan | | plans | list | | stats | get |

Body và response theo contract API. request mở cho endpoint bổ sung. Tạo/xoay/thu hồi API key và đổi gói cần JWT MONA Pass; API key cho app chỉ gọi các route cho phép key. Key live mm_live_ gửi thật; key test mm_test_ đi pipeline và kết thúc sandbox, không tính quota hay trừ ví. [email protected] chỉ gửi tới email chủ tài khoản. Địa chỉ khác cần domain verified.

Lỗi, retry và webhook

MonaMailError giữ status, code, message, next_step, request_id và payload gốc trong details. 402: dừng để nạp tiền hoặc duyệt gói. 403: kiểm domain, người nhận và quyền theo next_step. 429/5xx: retry tối đa 1 lần, giữ nguyên body và Idempotency-Key. Tôn trọng Retry-After; timeout áp cho từng request mạng. Mọi POST tự tạo key nếu chưa truyền. Dùng key ổn định theo tác vụ để tránh gửi trùng giữa các lần gọi SDK; TTL API là 24 giờ. Không tự retry lỗi mạng vì chưa biết server đã nhận tới đâu. App thử lại với key cũ. Webhook dùng HMAC SHA-256 của timestamp.raw_body; so sánh hằng thời gian, truyền thời gian hiện tại để chặn lệch hơn 300 giây. Giữ nguyên bytes body trước JSON parse và xử lý idempotent theo event id.

Đổi từ Resend

- import { Resend } from 'resend';
+ import { MonaMail } from 'monamail';
+ const resend = new MonaMail(process.env.MONAMAIL_API_KEY);

Thay constructor Resend cũ bằng dòng 3, giữ body gửi tương thích. Đây là bản Node; Python/PHP dùng constructor phía trên. MONA Mail trả email trực tiếp và ném exception; sửa chỗ đọc {data,error} của Resend. React Email và Broadcasts cần chuyển thành HTML hoặc giữ luồng cũ; không coi là tương thích tự động.

Cho AI agent

Đọc https://monamail.vn/agent-guide.md rồi dùng MONA Mail cho dự án.
Đăng nhập MONA Pass qua monacloud-mcp, đọc mail_account và chạy sandbox.
Tạo domain, xác minh DNS, tạo key rồi lưu MONAMAIL_API_KEY vào .env; không in key ra chat.
Gửi thử, kiểm mail_status, webhook bounced và suppression; báo lại kết quả thật.

Hợp đồng thao tác cho AI. Ví dụ framework ở ../examples.

English

MONA Mail is a transactional email API for Vietnamese developers and AI agents, billed in VND through VietQR. It belongs to MONA Cloud, The MONA Group. Install with the command at the top, export MONAMAIL_API_KEY and MONAMAIL_OWNER_EMAIL, and send your first message. The CLI examples read exported environment variables; load your .env through your framework or shell. Use a verified sender domain, or send from [email protected] to the account owner's email only. Test keys never deliver to the Internet and do not consume quota or wallet balance. All POST requests carry an idempotency key and retry once on 429/5xx with the same key and body. Provide a stable application key when retrying across SDK calls. Handle typed errors with their HTTP status, API code, next step and request ID. Verify webhook signatures using the exact raw request body, pass the current Unix time to enforce the 300-second window, and deduplicate by event ID. The migration diff above replaces the import and constructor; adapt Resend's response/error wrapper to direct return values and exceptions. React Email/Broadcasts are separate migration work. For AI agents, read agent-guide.md, use MONA Pass with MCP, test in sandbox, then configure domain, key and bounce handling. Never expose keys in chat or source control.

MIT · Source · API docs