API Mailbox Domain

Tổng quan

Địa chỉ gốc của các endpoint trên trang này:

https://cloudmoon.net/api/v1

Giá đại lý: Danh mục, báo giá và lệnh mua trả về (và trừ ví) giá đã trừ chiết khấu theo cấp đại lý; gia hạn theo GIÁ ĐANG GHI TRÊN ĐƠN (price_buy hiện tại: giá lúc mua đã trừ chiết khấu khi ấy, đổi theo khi nâng gói hoặc đổi chu kỳ). — xem mục Tài khoản đại lý.

Mua & theo dõi

Mỗi hộp thư là một đơn riêng (order_code, hạn và gia hạn riêng). Một lệnh mua tạo từ 1 tới 50 hộp trên cùng một tên miền, cùng gói và chu kỳ — trừ tiền một lần cho cả lô rồi tạo hộp luôn trong lượt gọi (thường vài giây tới vài chục giây — đặt thời gian chờ HTTP từ 90 giây).

1. GET /mailbox/products cho biết gói đang bán, chu kỳ mua được (cycles), giá một hộp từng chu kỳ (pricing) và các miền chung dùng được (shared_domains). GET /mailbox/check?email=… cho biết một địa chỉ còn tạo được không (status: available · taken · retired).
2. POST /mailbox/quote với cùng thân lệnh mua (khoá Chỉ đọc gọi được): chạy bộ kiểm đầu vào của lệnh mua — gói, chu kỳ, tên miền, tên từng hộp (còn trống theo dữ liệu tại đây) — rồi trả amount (tổng sẽ trừ), price_each và enough (số dư khả dụng đủ chưa).
3. POST /mailbox/buy với {product_id, billing_cycle, domain_type, shared_domain? | domain?, mailboxes} và header Idempotency-Key: hệ thống kiểm lại, hỏi hệ thống email từng địa chỉ, trừ ví rồi tạo hộp. Thường nhận HTTP 200 + provision_status: "ready" + mailboxes — mỗi hộp order_code · email · password.

• Mật khẩu: bỏ trống password ⇒ hệ thống sinh 16 ký tự; tự đặt thì 8–64 ký tự ASCII in được (0x21–0x7E — chữ không dấu, số, ký tự đặc biệt, không khoảng trắng). Mật khẩu chỉ có trong câu trả lời đầu tiên: gửi lại cùng Idempotency-Key thì bản phát lại để password: null kèm secrets_omitted. Đọc lại bất cứ lúc nào ở GET /mailbox/credentials (khoá Toàn quyền).
• Tên hộp (username): 1–64 ký tự a-z · 0-9 · . _ - (chữ hoa tự đổi về thường); bỏ trống ⇒ hệ thống đặt tên. Trên miền chung, một số tên dành riêng không mua được (409 MAILBOX_TAKEN). name là tên hiển thị của hộp, tối đa 120 ký tự.
• Hệ thống email chậm ⇒ HTTP 202 + provisioning + charged: true: các đơn đã tồn tại và đã trả tiền — đừng mua lại; mật khẩu đã chốt vẫn có trong mailboxes. Hỏi GET /mailbox/info?order_code=… tới khi ready.
• Đã trừ tiền mà chưa tạo được hộp ⇒ HTTP 200 + provision_status: "failed" + charged: true (ví dụ dưới). Tiền không tự hoàn — bộ phận hỗ trợ được báo và xử lý (tạo lại, hoặc huỷ và hoàn tiền — khi ấy info báo refunded_amount). Đừng gửi lại lệnh mua.
• Lệnh bị chối ở bước kiểm — thiếu tiền (402), địa chỉ đã có người dùng (409 MAILBOX_TAKEN, data.email = địa chỉ vướng), tên miền chưa có bằng chứng (409 DOMAIN_NOT_VERIFIED), gói / chu kỳ không bán… — thì chưa trừ đồng nào. 409 PRICE_CHANGED: giá vừa đổi giữa lúc kiểm và lúc trừ — báo giá lại rồi gửi lệnh mới với Idempotency-Key mới. Ngoại lệ: 400 FAILED ở lệnh mua có thể là giao dịch chưa rõ kết quả — đừng mua lại ngay: đối chiếu /mailbox/list hoặc liên hệ hỗ trợ.
• Hết thời gian chờ, mất câu trả lời: gửi lại với đúng Idempotency-Key cũ ⇒ nhận lại kết quả lần đầu (không kèm mật khẩu), hoặc 409 IDEMPOTENCY_PENDING khi lượt đầu chưa xong.
• price_each = giá một hộp · price_buy ở câu trả lời lệnh mua = tổng cả lô đã trừ (ở list / info, price_buy là giá của một hộp ấy). Các trường order_code · email ở cấp data là của hộp đầu tiên.

{
    "status": "success",
    "msg": "Đã trừ tiền nhưng chưa khởi tạo được hộp thư — hỗ trợ sẽ xử lý",
    "data": {
        "order_code": "171026MAILBOXQWERTYUIOPAS",
        "email": "[email protected]",
        "domain": "mail-chung.example",
        "domain_type": "shared",
        "domain_source": null,
        "provision_status": "failed",
        "charged": true,
        "product_id": 1,
        "billing_cycle": "onemonth",
        "count": 1,
        "price_each": 40000,
        "price_buy": 40000,
        "time_expire": "2026-11-17 14:30:00",
        "mailboxes": [
            {
                "order_code": "171026MAILBOXQWERTYUIOPAS",
                "email": "[email protected]",
                "password": null
            }
        ],
        "note": "Đã trừ tiền nhưng chưa khởi tạo được hộp thư — bộ phận hỗ trợ sẽ xử lý (không cần gửi lại lệnh)."
    }
}

Tên miền & xác minh

• domain_type: "shared" — địa chỉ trên một miền chung của hệ thống (một miền trong shared_domains; bỏ trống shared_domain = miền đầu tiên). Không cần xác minh, không cần bản ghi DNS.
• domain_type: "own" + domain — tên miền của bạn. Hệ thống cần một bằng chứng bạn quản lý tên miền ấy (proof ở /mailbox/verify-domain):
  • registered_here — tên miền đăng ký tại đây, đơn tên miền đang chạy của chính tài khoản (kể cả khi trỏ nameserver nơi khác) — đạt ngay;
  • txt — bản ghi TXT xác minh đạt trong 7 ngày gần nhất;
  • existing_mail_domain — tên miền thư đã thuộc chính tài khoản và tài khoản từng xác minh TXT tên miền ấy: mua thêm hộp không phải xác minh lại.
  Thiếu ⇒ 409 DOMAIN_NOT_VERIFIED + data.record (bản ghi cần thêm; null = chưa có mã — gọi verify-domain) — chưa trừ tiền.

Xác minh bằng bản ghi TXT

1. POST /mailbox/verify-domain với {domain} ⇒ record = bản ghi TXT cần thêm: tên _mbx-verify.<tên miền>, giá trị 32 ký tự riêng của tài khoản, cố định tới khi đạt.
2. Thêm bản ghi tại nơi quản lý DNS của tên miền — TXT đặt trực tiếp tại đúng tên ấy (CNAME không tính), giá trị đúng từng ký tự.
3. Gọi lại kèm check: true ⇒ verified: true, hoặc verified: false + result (not_found · wrong_value · cname). Đừng gửi check: true trước khi thêm bản ghi: hệ thống DNS có thể nhớ "chưa có" một thời gian.

• Nhịp: mỗi tên miền một lượt kiểm / 10 giây · tối đa 30 lượt kiểm / giờ / tài khoản · 30 tên miền mới / ngày (429). Mã chưa xác minh mà quá 30 ngày kể từ lần cấp và lần kiểm gần nhất thì bị dọn — gọi lại để nhận mã mới.
• Đã có bằng chứng mà tên miền đang thuộc tài khoản khác (đơn tên miền đang chạy, hoặc tên miền thư có hộp của người khác) ⇒ lệnh mua và check nhận 409 DOMAIN_IN_USE — liên hệ hỗ trợ (chưa có bằng chứng thì gặp 409 DOMAIN_NOT_VERIFIED trước). Tên miền thuộc hạ tầng của hệ thống, hoặc gửi miền chung với own ⇒ 400 DOMAIN_FORBIDDEN.
• Nguồn DNS (domain_source): managed — tên miền nằm trong tài khoản (đơn tên miền đang chạy) và dùng DNS quản lý tại đây: hệ thống tự ghi bộ bản ghi thư · external — DNS ở nơi khác: bạn tự thêm bản ghi (mục Bản ghi DNS thư). Bỏ trống ⇒ hệ thống tự chọn (managed khi đủ điều kiện) — nên để trống. Tên miền đã có hộp thư: nguồn là managed chỉ khi tên miền thư đang được hệ thống ghi DNS và vẫn đủ điều kiện trên (ví dụ chưa trỏ nameserver đi nơi khác); còn lại là external. Gửi managed khi nguồn thật là external ⇒ 409 DNS_EXTERNAL; gửi external khi nguồn thật là managed ⇒ 400.

Bản ghi DNS thư

Hộp trên tên miền riêng cần bộ bốn bản ghi để nhận thư và để thư gửi đi không bị coi là thư rác:

Giá trị đúng cho tên miền của bạn lấy ở GET /mailbox/dns?domain=…: records — mỗi bản ghi kèm found (đã thấy trên DNS công cộng) và found_values; all_found: true khi đủ cả bộ. Đừng chép giá trị từ ví dụ.

• managed: hệ thống tự ghi bộ bản ghi vào DNS tại đây ngay sau khi trừ tiền, trong lúc tạo hộp — chỉ đúng bộ bản ghi thư: thay MX và SPF ở gốc tên miền (thư của tên miền chuyển về đây), đặt DKIM, thêm DMARC khi chưa có; bản ghi khác của bạn để yên. Ghi chưa trọn ⇒ dns_status: "pending" — gọi POST /mailbox/dns/autowrite (cũng dùng để ghi lại khi lỡ xoá); bản ghi đã đúng được giữ nguyên. Mỗi tên miền một lượt tự ghi / 60 giây.
• external: thêm bộ bản ghi tại nơi quản lý DNS của tên miền; DNS cần từ vài phút tới vài giờ để lan truyền — kiểm bằng GET /mailbox/dns. dns_status của các hộp này luôn là external (hệ thống không tự kiểm hộ).
• dns_status ở list / info: not_required (miền chung) · configured (hệ thống đã ghi xong ở DNS tại đây — chưa chắc đã lan truyền, xem all_found) · pending (chưa ghi xong) · external.
• GET /mailbox/dns chỉ nhận tên miền thư mà chính tài khoản làm chủ (hộp nhận chuyển quyền trên tên miền của người khác ⇒ 404); tối đa 20 lượt / phút / tài khoản — lượt chạy thử cũng tính vì vẫn tra DNS thật.
• Xoá hộp cuối cùng của một tên miền riêng ⇒ hệ thống dọn tên miền thư ở hệ thống email và đúng bộ bản ghi thư mà nó đã ghi vào DNS tại đây (có thể xong sau ít phút).

Kết nối & mật khẩu

Tên đăng nhập là địa chỉ email đầy đủ. Tên máy chủ nằm ở connection của /mailbox/info và trong /mailbox/credentials:

• GET /mailbox/credentials (khoá Toàn quyền): email, mật khẩu đang lưu và thông số kết nối — chỉ hộp đang hoạt động, không bị khoá.
• POST /mailbox/change-password với {new_password?} — bỏ trống ⇒ hệ thống sinh 16 ký tự. Mật khẩu mới chỉ có trong câu trả lời này. Hệ thống email chối ⇒ 503 UNAVAILABLE (chưa đổi — gửi lại được); mất phản hồi rồi vẫn chưa xác nhận được ⇒ 400 FAILED: mật khẩu có thể đã đổi — đặt lại một mật khẩu mới. ⚠ Mật khẩu cũ có thể còn đăng nhập được thêm một lúc ngắn sau khi đổi (thường vài giây, có lúc tới khoảng 3 phút) — đổi vì lộ mật khẩu thì kiểm lại sau vài phút.
• POST /mailbox/webmail ⇒ webmail_url: đường đăng nhập webmail một lần, mở thẳng hộp thư trong trình duyệt không cần gõ mật khẩu. Giữ kín như mật khẩu; chưa dùng thì còn hiệu lực ít nhất 15 phút; mỗi lượt gọi xin một mã mới (mã cũ chưa dùng không bị huỷ — đừng gọi thừa); đổi mật khẩu hộp làm mọi mã chưa dùng mất hiệu lực.
• Gửi thư: mỗi hộp gửi tối đa smtp_sent_limit người nhận trong 24 giờ gần nhất — số của gói ở /mailbox/products (một thư gửi 3 người tính 3). Chạm giới hạn, hoặc lượng gửi tăng bất thường, hệ thống tự tạm ngưng gửi của hộp ấy (vẫn nhận), rồi tự mở lại khi lượng gửi trong 24 giờ xuống dưới 90% giới hạn. Gửi bản tin / thư quảng cáo số lượng lớn hãy dùng dịch vụ gửi thư hàng loạt.

Trạng thái hộp thư

provision_status gộp trạng thái thành một chữ cho bộ tích hợp — cùng tên với các sản phẩm khác; order_status cho biết chi tiết. Mỗi ô bên trái ghi provision_status ở trên, order_status ở dưới:

• allowed_actions (ở cả list lẫn info) — việc làm được ngay lúc này, cùng luật với các nút trên trang quản lý hộp thư: renew · auto_renew · upgrade · change_cycle · change_password · credentials · webmail · note · delete · stats. Tên nào vắng mặt thì lệnh ấy đang bị chối. Không tính nhịp thao tác, lượt gia hạn trong ngày hay số dư — xem mục Nhịp thao tác.
• charged luôn là true: mọi hộp được tạo cùng lượt trừ tiền. billing: price_buy · price_renew (giá gia hạn kỳ tới = giá ghi trên đơn) · billing_cycle · months · renew_auto · time_buy · time_expire.
• list trả mọi hộp của tài khoản — mua trên web lẫn qua API, nhận chuyển quyền — mặc định bỏ hộp đã huỷ; lọc bằng ?status= theo provision_status (nhận cả giá trị order_status), ?domain=, ?domain_type=.
• GET /mailbox/stats: thư gửi · thư nhận · thư rác bị chặn · dung lượng · lượt đăng nhập theo ngày / tuần / tháng (by) — hệ thống nhớ kết quả 30 phút.

Gia hạn & hết hạn

• POST /mailbox/renew với {order_code} gia hạn một chu kỳ và trừ ví ngay: amount = giá ghi trên đơn (billing.price_renew — giá lúc mua đã trừ chiết khấu khi ấy, đổi theo khi nâng gói hoặc đổi chu kỳ; báo giá: quote với {"type": "renew", "order_code": "…"}). Hạn mới = max(hôm nay, hạn cũ) + một chu kỳ.
• Mỗi hộp một lượt gia hạn mỗi ngày, tính cả gia hạn trên web và tự gia hạn; ngày mua đã tính là lượt của ngày ấy ⇒ 429 COOLDOWN, Retry-After tới 0 giờ.
• Hộp có giá ghi trên đơn bằng 0 không gia hạn được ở bất kỳ đường nào — web, tự gia hạn hay API (renew vắng trong allowed_actions, lệnh nhận 400 NOT_SUPPORTED) — liên hệ hỗ trợ.
• Quá hạn: qua time_expire mà chưa gia hạn, ở lượt kiểm hằng đêm kế tiếp hộp ngừng hoạt động (pending_expired): hộp bị gỡ khỏi hệ thống email, thư được giữ dạng bản sao tới restore_deadline (30 ngày sau). Gia hạn trong khoảng ấy ⇒ hệ thống khôi phục hộp kèm thư cũ trước, có hộp rồi mới trừ tiền (mailbox_data: "restored"; bản sao không còn ⇒ hộp mới rỗng cùng địa chỉ, "new"). Chưa khôi phục được ⇒ 503 UNAVAILABLE, chưa trừ tiền — gửi lại sau (kể cả cùng Idempotency-Key).
• Quá restore_deadline ⇒ expired: hộp và thư bị xoá vĩnh viễn. Vẫn gia hạn được — hệ thống tạo hộp mới rỗng cùng địa chỉ (mailbox_data: "new"); mật khẩu đọc lại ở credentials.
• Tự gia hạn (billing.renew_auto; đặt bằng POST /mailbox/auto-renew với enabled là boolean — lệnh ĐẶT giá trị, gửi lại cùng giá trị không lật ngược): khi còn 7 ngày hoặc ít hơn tới time_expire — kể cả lúc hộp đã ngừng hoạt động vì quá hạn — mỗi giờ hệ thống thử gia hạn một chu kỳ theo giá ghi trên đơn; số dư thiếu ⇒ bỏ qua, thử lại giờ sau. Hộp hết thời gian lưu không tự gia hạn — gia hạn tay.
• Nâng gói (POST /mailbox/upgrade với {order_code, product_id}): chỉ lên gói dung lượng lớn hơn đang bán — không có hạ gói. Trừ ngay phần chênh lệch theo số ngày còn lại (tròn lên 1.000đ); dung lượng đổi ngay ở hệ thống email; kỳ sau gia hạn theo giá gói mới (price_renew). Chưa đổi được dung lượng ⇒ trả gói cũ + hoàn tiền, 503; hoàn tiền / trả gói chưa xác nhận được ⇒ 400 FAILED — đừng gửi lại, liên hệ hỗ trợ.
• Đổi chu kỳ (POST /mailbox/change-cycle với {order_code, billing_cycle}): 0 đồng, hạn hiện tại giữ nguyên; giá chu kỳ mới (price_renew) áp từ lần gia hạn kế tiếp.
• Dịch vụ hộp thư tạm dừng bán (bảo trì), hay một miền chung / tên miền thôi nhận hộp mới, không chặn gia hạn, nâng gói, đổi chu kỳ hay bất kỳ lệnh nào trên hộp đang có.

Luật riêng

• Xoá (POST /mailbox/delete, confirm = đúng order_code): hộp bị xoá ở hệ thống email trước rồi đơn mới đóng — không hoàn tiền, thư không khôi phục được. Chưa xác nhận xoá được ⇒ 503, đơn giữ nguyên — gửi lại sau. Hộp đang tạo ⇒ 409 PROVISIONING. Địa chỉ đã xoá không tạo lại được (check: retired trên tên miền riêng, taken trên miền chung).
• Dịch vụ hộp thư tạm dừng bán: products · check · verify-domain · báo giá mua mới · lệnh mua nhận 503 SERVICE_DISABLED (GET /services/status báo mailbox: false); mọi lệnh trên hộp đang có vẫn chạy bình thường.
• Giới hạn lệnh mua (mỗi tài khoản): tối đa 10 lượt mua và 100 hộp mỗi giờ — đếm cả mua trên web (429 RATE_LIMITED), tính riêng với các sản phẩm khác; cộng 60 lần thử mua mỗi giờ qua API (lệnh bị chối sau bước hỏi hệ thống email cũng tính). Kiểm tên (check) tối đa 40 lượt / phút / tài khoản, chung với ô kiểm tên trên web. Số dư xét lệnh mua là số dư khả dụng — đã trừ tiền các lệnh mua Cloud VPS còn chờ tạo máy.
• Không làm qua API: chuyển hộp sang tài khoản khác · mua kèm đăng ký tên miền mới (đăng ký trước bằng API Domain, rồi mua hộp với domain_type: "own") · xem nhật ký hộp — dùng trang quản lý trên web.
• Chạy thử (X-Sandbox: 1): check không hỏi hệ thống email (status: "simulated" khi địa chỉ chưa có ở đây) · verify-domain không cấp mã, không tra DNS · lệnh mua trả mỗi hộp một mã SANDBOX… (28 ký tự) — hỏi info bằng mã ấy (vẫn kèm X-Sandbox: 1) ⇒ hộp mẫu ready ngay, địa chỉ mẫu sbx…@<miền> (tên miền riêng mẫu sandbox-….example); kịch bản PROVISION_FAILED ⇒ lệnh mua 202, info ở provisioning 10 giây đầu rồi failed. Mã chỉ chở gói, chu kỳ, miền chung, số hộp và cờ — không chở tên hộp. stats trả số mẫu; webmail trả địa chỉ webmail không kèm mã đăng nhập; GET /mailbox/dns vẫn tra DNS thật (tính vào giới hạn 20 lượt / phút). Mọi lệnh trên hộp mẫu đi đủ các bước kiểm rồi trả mô phỏng; không lưu gì: mã không có trong list.

Nhịp thao tác trên cùng một hộp thư

Các lệnh trên cùng một hộp thư phải cách lệnh trước một khoảng tối thiểu — nhịp này chỉ áp cho lệnh gửi qua API, để chặn lệnh gửi lặp. Các việc trong cùng một dòng dùng chung một đồng hồ. Gửi sớm hơn ⇒ 429 COOLDOWN (header Retry-After cho biết còn bao nhiêu giây); gửi trong lúc máy đang xử lý lệnh khác ⇒ 429 IN_PROGRESS.

Mã lỗi riêng

Ngoài các mã lỗi chung của mọi endpoint, trang này còn có các mã dưới đây. Hãy rẽ nhánh theo code.