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

Mục tiêu của trang này là một thư nhận được thật, không phải hiểu hết API. Hiểu hết là việc của 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 của bạn để 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 trong ví dụ là tối thiểu để gửi được. Danh sách 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 trong bảng điều khiển.

Đọc mã trả về

{ "id": "..." }

Mã trạng thái 202 nghĩa là đã nhận để gửi, không phải đã tới hộp thư người nhận. Đây là chỗ hay hiểu nhầm nhất: thư còn phải đi tiếp qua đường gửi, và có thể bị nơi nhận từ chối sau đó.

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

Mọi mã khác 202 đều là bị từ chối ngay, chưa gửi gì. Bảng đầy đủ ý nghĩa từng mã nằm trong mục Hướng dẫn của bảng điều khiển.

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 ở đầu. Chép lại khoá từ chỗ đã lưu — bảng danh sách trên bảng điều khiển chỉ hiện phần đầu mã, không dùng để chép được.

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. Sending Key chỉ gửi được đúng 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ý tra đúng thư đó — trạng thái ở đó mới là sự thật
3. Kiểm danh sách chặn: địa chỉ người nhận có thể đang bị chặn từ một lần gửi hỏng trước đó, và 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ý có dòng tương ứng với trạng thái thành công

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

Bước tiếp theo