Gửi thư đầu tiên qua Email API

Mục tiêu trang này là một thư nhận được thật, không phải hiểu hết API — phần đó nằm ở mục Hướng dẫn trong bảng điều khiển.

Chuẩn bị

• Tên miền gửi đã kích hoạt. Xem Cắm bản ghi cho tên miền gửi
• Một khoá API đã lưu. Xem Tạo khoá API để gửi thư
• Một hộp thư thật để nhận thư thử

Gọi lệnh gửi

Thay cf_... bằng khoá của bạn và example.com bằng tên miền gửi đã kích hoạt.

curl -X POST https://api-vmail.cloudfly.vn/api/emails \
  -H "Authorization: Bearer cf_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "no-reply@example.com",
    "to": "ban@example.net",
    "subject": "Thư thử đầu tiên",
    "text": "Nếu bạn đọc được dòng này thì Email API đã chạy."
  }'

Bốn trường trên là tối thiểu. Tham số đầy đủ — tệp đính kèm, mẫu thư, biến, người nhận ẩn — nằm ở Email API → Hướng dẫn.

Đọc mã trả về

{
  "success": true,
  "data": {
    "id": "em_a1b2c3d4e5f6",
    "from": "no-reply@example.com",
    "to": "ban@example.net",
    "status": "queued",
    "created_at": "2026-07-01T10:30:00Z"
  }
}

Mã thư nằm ở data.id, không phải id ở gốc — lưu lại để tra cứu. Mọi phản hồi đều bọc trong success + data, kể cả phản hồi lỗi.

Mã 202 nghĩa là đã nhận để gửi, không phải đã tới hộp thư: thư còn đi tiếp và có thể bị từ chối sau đó.

Muốn biết thư có tới hay không: Thống kê & Nhật ký, hoặc webhook nếu cần biết ngay trong mã nguồn.

Mọi mã khác 202 là bị từ chối ngay, chưa gửi gì — ý nghĩa từng mã ở Bảng tra mã lỗi Email API.

Ba lỗi hay gặp ở lần đầu

Bị từ chối xác thực

Khoá sai, đã bị xoá, hoặc header thiếu chữ Bearer . Chép lại khoá từ chỗ đã lưu — bảng điều khiển chỉ hiện phần đầu mã.

Bị từ chối quyền dù khoá đúng

Địa chỉ from không thuộc tên miền mà khoá được phép gửi. Hai nguyên nhân:

• Tên miền chưa kích hoạt xong — kiểm ở trang Tên miền gửi
• Khoá là Sending Key gắn tên miền khác — loại khoá này chỉ gửi được tên miền của nó

Trả về 202 mà không thấy thư

Theo thứ tự:

1. Kiểm thư mục rác của hộp thư nhận
2. Mở Thống kê & Nhật ký → tab Nhật ký, tra đúng thư đó — trạng thái ở đó mới là sự thật
3. Kiểm danh sách chặn: người nhận có thể đang bị chặn từ lần gửi hỏng trước, thư bị bỏ trước khi ra khỏi hệ thống

Kiểm tra kết quả

Xong khi cả ba đều đúng:

1. Lệnh gọi trả về 202
2. Thư có mặt trong hộp thư nhận, kể cả trong thư mục rác
3. Thống kê & Nhật ký → tab Nhật ký có dòng tương ứng, trạng thái thành công

Thư vào thư mục rác vẫn tính là gửi được. Muốn cải thiện thì bắt đầu từ bản ghi _dmarc ở trang tên miền gửi.

Bước tiếp theo