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 bảng đi từ triệu chứng bạn nhìn thấy. Dòng trên gặp nhiều hơn dòng dưới, nên đọc từ trên xuống và dừng ở dòng đầu tiên khớp.

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ã, kèm mã nào đáng thử lại: Bảng tra mã lỗi Email API.

Triệu chứng	Nguyên nhân	Xử lý
Bị từ chối xác thực	Header thiếu chữ `Bearer` — ca hay gặp nhất	Gửi đủ dạng `Authorization: Bearer <khoá>`
Bị từ chối xác thực	Khoá đã bị xoá	Đối chiếu phần đầu mã với cột Mã khóa (Preview) trên trang Khóa API
Bị từ chối xác thực	Khoá bị cắt khi lưu vào biến môi trường	Kiểm độ dài chuỗi ứng dụng thực sự gửi đi
Bị từ chối quyền	Tên miền trong `from` chưa kích hoạt	Cắm bản ghi cho tên miền gửi
Bị từ chối quyền	Khoá là Sending Key gắn tên miền khác; nó chỉ gửi được đúng tên miền của nó	Dùng khoá gắn đúng tên miền trong `from`
Bị từ chối quyền	Gõ nhầm tên miền trong `from`	Sửa lại `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`	Bổ sung trường còn thiếu
Bị từ chối vì dữ liệu	Thư vượt trần kích thước	Trần ghi ở mục Giới hạn trong Email API → Hướng dẫn
Bị từ chối vì quá nhiều yêu cầu	Vượt tốc độ gửi cho phép	Giãn nhịp, rải thư hàng loạt đều theo thời gian. Thử lại ngay chỉ làm nặng thêm

Hạn mức gói hiện trong bảng điều khiển.

Mã 202 nghĩa là đã nhận để gửi, không phải đã tới.

Kiểm theo thứ tự	Nếu đây là nguyên nhân
Thư mục rác của người nhận — bước bỏ qua nhiều nhất mà lại đúng nhiều nhất	Đọc tiếp mục Thư vào thư mục rác
Thống kê & Nhật ký → tab Nhật ký; trạng thái của đúng thư đó mới là sự thật	Bị trả lại nghĩa là nơi nhận đã từ chối — vấn đề ở địa chỉ người nhận hoặc uy tín tên miền
Danh sách chặn	Thư bị bỏ trước khi ra khỏi hệ thống
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

Màn hình mở ở tab Thống kê — số của cả tên miền, không phải thư bạn đang tìm:

Bấm Nhật ký ở góc phải tiêu đề để ra bảng từng thư
Thu hẹp bằng ô tìm kiếm (người nhận, tiêu đề hoặc Message ID) và bộ lọc Trạng thái
Bấm một dòng để xem trạng thái, lý do bị trả và số lần mở / bấm liên kết

Cách đọc các khối số ở tab Thống kê: Đọc trang Tổng quan.

Không phải lỗi kỹ thuật nên không có nút nào sửa được. Bảng xếp theo thứ tự ảnh hưởng.

Nguyên nhân	Xử lý
Thiếu bản ghi ký thư — thiếu một trong ba dòng là mất chữ ký	Cắm đủ cả ba dòng
Không có bản ghi `_dmarc`, hoặc nó mâu thuẫn với nguồn gửi	Thêm `_dmarc` không mâu thuẫn với nguồn gửi
Vẫn gửi cho người đã báo cáo thư rác — việc này làm hỏng uy tín của cả tên miền	Xử lý sự kiện `email.complained`, xem Nhận sự kiện thư qua webhook
Vẫn gửi cho địa chỉ đã bị trả cứng — tỷ lệ trả lại cao là chỉ số bị chấm điểm	Bỏ địa chỉ đó khỏi danh sách gửi

Kiểm	Nghĩa là
Endpoint có đang Tạm ngưng không	Trang webhook có nút bật lại. Sự kiện xảy ra lúc tạm ngưng không được lưu và không gửi bù
Sự kiện bạn cần có nằm trong danh sách đã chọn khi tạo không	Thiếu thì sự kiện đó không bao giờ được gửi tới
Lịch sử giao dịch có dòng báo Lỗi gửi	Endpoint của bạn trả mã lỗi, quá 10 giây hoặc không kết nối được. Hệ thống không tự gửi lại — sửa endpoint rồi bấm Gửi lại
Lịch sử giao dịch chưa có dòng nào	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

Gửi kèm bốn thứ này, chúng đủ để tra ra đúng bản ghi:

Đừ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á đó.