Tài liệu API và SDK MONA Mail

curl -sS -X GET "https://api.monamail.vn/v1/account" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.account.get();

client.account.get()

{
  "sub": "account_example",
  "email": "[email protected]",
  "name": "Anh An",
  "plan": {
    "slug": "free",
    "name": "Miễn phí",
    "monthly_limit": 3000,
    "overage_vnd_per_mail": null
  },
  "quota": {
    "limit": 3000,
    "used": 0,
    "remaining": 3000,
    "resets_at": "2026-10-01T00:00:00Z"
  },
  "domains": {
    "total": 0,
    "verified": 0
  },
  "onboarding_sender": "[email protected]",
  "sandbox_hint": "Dùng mm_test_",
  "next_step": "Gọi POST /v1/domains"
}

curl -sS -X GET "https://api.monamail.vn/v1/plans"

await client.plans.list();

client.plans.list()

[
  {
    "slug": "free",
    "name": "Miễn phí",
    "monthly_fee_vnd": 0,
    "monthly_limit": 3000,
    "overage_vnd_per_mail": null,
    "agent_inboxes": 1
  },
  {
    "slug": "khoi-nghiep",
    "name": "Khởi nghiệp",
    "monthly_fee_vnd": 99000,
    "monthly_limit": 30000,
    "overage_vnd_per_mail": 3,
    "agent_inboxes": 5
  },
  {
    "slug": "kinh-doanh",
    "name": "Kinh doanh",
    "monthly_fee_vnd": 299000,
    "monthly_limit": 150000,
    "overage_vnd_per_mail": 2,
    "agent_inboxes": 25
  },
  {
    "slug": "doanh-nghiep",
    "name": "Doanh nghiệp",
    "monthly_fee_vnd": 799000,
    "monthly_limit": 600000,
    "overage_vnd_per_mail": 1.5,
    "agent_inboxes": 100
  }
]

curl -sS -X PUT "https://api.monamail.vn/v1/account/plan" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan":"khoi-nghiep"}'

await client.account.setPlan("khoi-nghiep");

client.account.set_plan("khoi-nghiep")

curl -sS -X GET "https://api.monamail.vn/v1/api-keys" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.apiKeys.list();

client.api_keys.list()

curl -sS -X POST "https://api.monamail.vn/v1/api-keys" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"app","mode":"test"}'

await client.apiKeys.create({name:"app",mode:"test"});

client.api_keys.create(name="app", mode="test")

curl -sS -X POST "https://api.monamail.vn/v1/api-keys/key_example/rotate" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY"

await client.apiKeys.rotate("key_example");

client.api_keys.rotate("key_example")

curl -sS -X DELETE "https://api.monamail.vn/v1/api-keys/key_example" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.apiKeys.revoke("key_example");

client.api_keys.revoke("key_example")

curl -sS -X GET "https://api.monamail.vn/v1/domains" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.domains.list();

client.domains.list()

curl -sS -X POST "https://api.monamail.vn/v1/domains" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"shop.vn"}'

await client.domains.create({domain:"shop.vn"});

client.domains.create(domain="shop.vn")

{
  "id": "dom_example",
  "domain": "shop.vn",
  "status": "pending",
  "records": [
    {
      "type": "TXT",
      "name": "mona1._domainkey.shop.vn",
      "value": "v=DKIM1; k=rsa; p=BASE64_FROM_RECORDS",
      "purpose": "dkim",
      "required": true
    },
    {
      "type": "TXT",
      "name": "shop.vn",
      "value": "v=spf1 include:_spf.monamail.vn ~all",
      "purpose": "spf",
      "required": false
    },
    {
      "type": "TXT",
      "name": "_dmarc.shop.vn",
      "value": "v=DMARC1; p=none; rua=mailto:[email protected]",
      "purpose": "dmarc",
      "required": false
    }
  ],
  "checks": {
    "dkim": "missing",
    "spf": "missing",
    "dmarc": "missing"
  },
  "verified_at": null,
  "created_at": "2026-09-05T00:00:00Z",
  "daily_limit": 500
}

curl -sS -X GET "https://api.monamail.vn/v1/domains/dom_example" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.domains.get("dom_example");

client.domains.get("dom_example")

curl -sS -X POST "https://api.monamail.vn/v1/domains/dom_example/verify" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY"

await client.domains.verify("dom_example");

client.domains.verify("dom_example")

curl -sS -X DELETE "https://api.monamail.vn/v1/domains/dom_example" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.domains.remove("dom_example");

client.domains.remove("dom_example")

curl -sS -X POST "https://api.monamail.vn/v1/domains/dom_example/cloudflare" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_token":"CF_TOKEN_FROM_ENV"}'

await client.domains.cloudflare("dom_example",{api_token:process.env.CLOUDFLARE_API_TOKEN});

client.domains.cloudflare("dom_example", api_token=os.environ["CLOUDFLARE_API_TOKEN"])

curl -sS -X POST "https://api.monamail.vn/v1/emails" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"[email protected]","to":"[email protected]","subject":"Thử mail","text":"Xin chào","tags":["transactional"]}'

await client.emails.send({"from": "[email protected]", "to": "[email protected]", "subject": "Thử mail", "text": "Xin chào", "tags": ["transactional"]});

client.emails.send({'from': '[email protected]', 'to': '[email protected]', 'subject': 'Thử mail', 'text': 'Xin chào', 'tags': ['transactional']})

{
  "id": "em_example",
  "status": "queued",
  "deliveries": [
    {
      "to": "[email protected]",
      "status": "queued"
    }
  ],
  "quota": {
    "used": 1,
    "remaining": 2999
  }
}

curl -sS -X POST "https://api.monamail.vn/v1/emails/batch" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":[{"from":"[email protected]","to":"[email protected]","subject":"Thử mail","text":"Xin chào","tags":["transactional"]}]}'

await client.emails.batch({emails:[message]});

client.emails.batch([message])

curl -sS -X GET "https://api.monamail.vn/v1/emails/em_example" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.emails.get("em_example");

client.emails.get("em_example")

curl -sS -X GET "https://api.monamail.vn/v1/emails?limit=20&status=delivered" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.emails.list({limit:20,status:"delivered"});

client.emails.list(limit=20,status="delivered")

curl -sS -X POST "https://api.monamail.vn/v1/emails/em_example/cancel" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY"

await client.emails.cancel("em_example");

client.emails.cancel("em_example")

curl -sS -X GET "https://api.monamail.vn/v1/emails/em_example/events" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.emails.events("em_example");

client.emails.events("em_example")

curl -sS -X GET "https://api.monamail.vn/v1/webhooks" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.webhooks.list();

client.webhooks.list()

curl -sS -X POST "https://api.monamail.vn/v1/webhooks" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://shop.vn/webhooks/monamail","events":["email.bounced"]}'

await client.webhooks.create({url:"https://shop.vn/webhooks/monamail",events:["email.bounced"]});

client.webhooks.create(url="https://shop.vn/webhooks/monamail", events=["email.bounced"])

curl -sS -X POST "https://api.monamail.vn/v1/webhooks/wh_example/rotate" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY"

await client.webhooks.rotate("wh_example");

client.webhooks.rotate("wh_example")

curl -sS -X POST "https://api.monamail.vn/v1/webhooks/wh_example/test" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY"

await client.webhooks.test("wh_example");

client.webhooks.test("wh_example")

curl -sS -X DELETE "https://api.monamail.vn/v1/webhooks/wh_example" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.webhooks.remove("wh_example");

client.webhooks.remove("wh_example")

curl -sS -X GET "https://api.monamail.vn/v1/webhooks/wh_example/deliveries?limit=20" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.webhooks.deliveries("wh_example",{limit:20});

client.webhooks.deliveries("wh_example",limit=20)

curl -sS -X GET "https://api.monamail.vn/v1/suppressions?limit=20" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.suppressions.list({limit:20});

client.suppressions.list(limit=20)

curl -sS -X POST "https://api.monamail.vn/v1/suppressions" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","reason":"manual"}'

await client.suppressions.add({email:"[email protected]",reason:"manual"});

client.suppressions.add(email="[email protected]",reason="manual")

curl -sS -X DELETE "https://api.monamail.vn/v1/suppressions/a%40example.com" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.suppressions.remove("[email protected]");

client.suppressions.remove("[email protected]")

curl -sS -X GET "https://api.monamail.vn/v1/templates" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.templates.list();

client.templates.list()

curl -sS -X POST "https://api.monamail.vn/v1/templates" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"otp","subject":"Mã OTP","html":"<b>OTP</b>"}'

await client.templates.create({name:"otp",subject:"Mã OTP",html:"<b>OTP</b>"});

client.templates.create(name="otp",subject="Mã OTP",html="<b>OTP</b>")

curl -sS -X GET "https://api.monamail.vn/v1/templates/tpl_example" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.templates.get("tpl_example");

client.templates.get("tpl_example")

curl -sS -X PUT "https://api.monamail.vn/v1/templates/tpl_example" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Mã đăng nhập"}'

await client.templates.update("tpl_example",{subject:"Mã đăng nhập"});

client.templates.update("tpl_example",subject="Mã đăng nhập")

curl -sS -X DELETE "https://api.monamail.vn/v1/templates/tpl_example" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.templates.remove("tpl_example");

client.templates.remove("tpl_example")

curl -sS -X POST "https://api.monamail.vn/v1/templates/tpl_example/render" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Idempotency-Key: $MONAMAIL_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"otp":"123456"}}'

await client.templates.render("tpl_example",{variables:{otp:"123456"}});

client.templates.render("tpl_example",variables={"otp":"123456"})

curl -sS -X GET "https://api.monamail.vn/v1/stats?from=2026-09-01&to=2026-09-05" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

await client.stats.get({from:"2026-09-01",to:"2026-09-05"});

client.stats.get(**{"from":"2026-09-01","to":"2026-09-05"})

curl -sS -X POST "https://api.monamail.vn/v1/inboxes" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"info"}'

curl -sS -X GET "https://api.monamail.vn/v1/inboxes" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

curl -sS -X GET "https://api.monamail.vn/v1/inboxes/123" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

curl -sS -X DELETE "https://api.monamail.vn/v1/inboxes/123" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

curl -sS -X GET "https://api.monamail.vn/v1/inboxes/123/messages?limit=50" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

curl -sS -X GET "https://api.monamail.vn/v1/inboxes/123/messages/456" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

curl -sS -X GET "https://api.monamail.vn/v1/inboxes/123/messages/456/attachments/789" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

curl -sS -X POST "https://api.monamail.vn/v1/inboxes/123/messages/456/reply" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Nội dung thư trả lời..."}'

curl -sS -X GET "https://api.monamail.vn/v1/inboxes/123/wait?match=otp&timeout=120" \
  -H "Authorization: Bearer $MONAMAIL_TOKEN"

curl -sS -X GET "https://api.monamail.vn/v1/healthz"

await client.request("GET","/healthz");

client.request("GET","/healthz")