Xử lý sự cố Email API
Đi từ triệu chứng tới nguyên nhân theo thứ tự, cho các ca thư không gửi được, gửi được mà không tới, và bị từ chối vì quá hạn mức.
Mỗi mục dưới đây bắt đầu từ triệu chứng bạn nhìn thấy, không phải từ tên lỗi. Đi theo thứ tự trong mục và dừng ở bước đầu tiên cho kết quả bất thường.
Trước tiên: phân biệt hai loại sự cố
Đây là câu hỏi chia đôi mọi việc còn lại.
| Lệnh gọi trả về | Nghĩa là | Đọc mục |
|---|---|---|
| mã không phải 202 | thư chưa vào hệ thống | Lệnh gọi bị từ chối |
| mã 202 | thư đã vào hệ thống, sự cố nằm ở sau đó | Trả về 202 mà thư không tới |
Ý nghĩa từng mã trả về nằm ở Email API → Hướng dẫn trong bảng điều khiển, cùng hành động khuyến nghị cho mỗi mã.
Lệnh gọi bị từ chối
Bị từ chối xác thực
- Header phải có đủ dạng
Authorization: Bearer <khoá>. Thiếu chữBearerlà ca hay gặp nhất - Khoá đã bị xoá? Đối chiếu phần đầu mã ở cột Mã khóa (Preview) trên trang Khóa API
- Khoá bị cắt khi lưu vào biến môi trường — kiểm độ dài chuỗi thực sự ứng dụng đang gửi
Bị từ chối quyền
Khoá đúng nhưng không được phép gửi từ địa chỉ đó.
- Tên miền trong
fromđã kích hoạt chưa? Xem Cắm bản ghi cho tên miền gửi - Khoá có phải Sending Key gắn tên miền khác không? Nó chỉ gửi được đúng tên miền của nó
- Gõ nhầm tên miền trong
from
Bị từ chối vì dữ liệu
Thiếu trường bắt buộc, hoặc có to nhưng không có cả text lẫn html. Thư quá lớn cũng bị từ chối
ngay — giới hạn kích thước nằm trong bảng hạn mức ở mục Hướng dẫn.
Bị từ chối vì quá nhiều yêu cầu
Bạn vượt tốc độ gửi cho phép. Cách xử lý là giãn nhịp gửi, không phải thử lại ngay — thử lại ngay chỉ làm tình hình xấu hơn.
Gửi hàng loạt thì rải đều theo thời gian thay vì bắn hết một lúc. Hạn mức của gói bạn đang dùng hiện trong bảng điều khiển.
Trả về 202 mà thư không tới
Mã 202 nghĩa là đã nhận để gửi, không phải đã tới. Đi theo thứ tự:
- Thư mục rác của người nhận. Bước này bỏ qua nhiều nhất mà lại đúng nhiều nhất
- Thống kê & Nhật ký. Tra đúng thư đó — trạng thái ở đây mới là sự thật
- Danh sách chặn. Địa chỉ người nhận có trong đó thì thư bị bỏ trước khi ra khỏi hệ thống. Xem Đọc và xử lý danh sách chặn
- Bản ghi DNS của tên miền gửi. Thiếu bản ghi ký thư thì thư đi được nhưng hay bị nơi nhận xếp vào rác
Nhật ký ghi trạng thái bị trả lại nghĩa là nơi nhận đã từ chối — vấn đề nằm ở địa chỉ người nhận hoặc ở uy tín tên miền, không phải ở lệnh gọi của bạn.
Thư vào thư mục rác
Không phải lỗi kỹ thuật, nên không có một nút nào sửa được. Theo thứ tự ảnh hưởng:
- Cắm đủ bản ghi ký thư — thiếu một trong ba dòng là mất chữ ký
- Có bản ghi
_dmarcvà nó không mâu thuẫn với nguồn gửi - Xử lý sự kiện
email.complained— tiếp tục gửi cho người đã báo cáo thư rác làm hỏng uy tín của cả tên miền. Xem Nhận sự kiện thư qua webhook - Đừng gửi cho địa chỉ đã bị trả cứng — tỉ lệ trả lại cao là chỉ số bị chấm điểm
Webhook không nhận được gì
- Endpoint có đang Tạm ngưng không? Trang webhook có nút bật lại
- Sự kiện bạn cần có nằm trong danh sách đã chọn khi tạo không?
- Lịch sử giao dịch có dòng nào không? Có dòng mà cột Lần gửi tăng dần nghĩa là endpoint của bạn đang trả mã lỗi
- Chưa có dòng nào nghĩa là chưa có sự kiện nào xảy ra — thử gửi một thư tới địa chỉ chắc chắn không tồn tại để tạo ra một sự kiện trả lại
Khi cần báo bộ phận hỗ trợ
Gửi kèm bốn thứ này, chúng đủ để tra ra đúng bản ghi:
- Tên miền gửi
- Thời điểm gần đúng, kèm múi giờ
- Địa chỉ người nhận
- Mã trả về của lệnh gọi, hoặc trạng thái hiện trong Thống kê & Nhật ký
Đừng gửi kèm khoá API. Không ai cần nó để tra cứu, và gửi đi là phải thu hồi khoá đó.