Kiểm tra trạng thái gửi email qua API trước khi thử lại

API hết thời gian chờ chưa đủ để kết luận gửi thất bại. Nếu đã có mã lần gửi, hãy gọi GET /sends/{id} trước khi thử lại. Với unknown, tạm dừng gửi lại tự động để đối soát; với queued hoặc sending, tiếp tục theo dõi lần gửi cũ. Trạng thái sent cũng không chứng minh thư đã vào hộp thư đến.

Vì sao hết thời gian chờ chưa có nghĩa là gửi thất bại?

Hết thời gian chờ cho biết ứng dụng không nhận được phản hồi trong thời gian chờ của nó. Đừng dùng riêng tín hiệu đó để quyết định gửi thêm một bản.

Một lần gửi là thao tác gửi mà bạn cần theo dõi bằng mã riêng. Hãy tách ba lớp thông tin:

Ví dụ, tài liệu Microsoft Graph sendMail nêu rằng 202 Accepted nghĩa là yêu cầu đã được chấp nhận, không có nghĩa việc xử lý đã hoàn tất.

RFC 5321 về SMTP cũng mô tả thư có thể đi qua các máy chủ chuyển tiếp trước khi tới người nhận cuối cùng. Vì vậy, phản hồi của một thao tác gửi và vị trí thư ở đầu nhận là hai việc khác nhau.

Mailera kết nối các hộp thư bạn đang dùng với ứng dụng. Trong REST API của Mailera, endpoint cần dùng ở đây là GET /sends/{id}, không phải GET /mailboxes/{id}/status: endpoint thứ hai kiểm tra tình trạng đăng nhập hộp thư.

Kiểm tra trạng thái gửi bằng Mailera như thế nào?

1. Giới hạn khoá API đúng phạm vi

Trong Cài đặt, mở phần khoá API rồi chọn Tạo key. Đặt Tên gợi nhớ, chọn một nhóm trong Phạm vi hộp thư và cấp quyền send. Admin có thể chọn tất cả nhóm, nhưng bạn nên giới hạn vào nhóm phục vụ công việc này.

GET /sends/{id} yêu cầu quyền send, dù thao tác là tra cứu. Không thêm read hoặc manage nếu quy trình không cần chúng. Lưu khoá vào biến môi trường $MAILERA_API_KEY, không đưa vào mã nguồn hay nhật ký.

2. Lưu mã lần gửi cùng mã công việc

Nếu đã có mã lần gửi, lưu mã đó cùng mã công việc để tra cứu bằng GET /sends/{id}. Giữ riêng mã hộp thư và mã lần gửi; chúng phục vụ các endpoint khác nhau.

Nên lưu cả thời điểm gửi, kết quả gần nhất và Idempotency-Key nếu đã sử dụng.

3. Tra cứu đúng lần gửi

Gửi yêu cầu GET tới https://mailera.app/api/public/v1/sends/{id}, thay {id} bằng mã lần gửi đã lưu. Dùng header Authorization: Bearer $MAILERA_API_KEY; trong ứng dụng, lấy giá trị khoá từ biến môi trường tương ứng.

Đối chiếu cấu trúc phản hồi khi triển khai tại tài liệu API Mailera. Sau mỗi lần tra cứu, ghi lại kết quả và thời điểm nhận được để tiến trình tiếp theo không phải đoán trạng thái cũ.

4. Tách nhánh không có mã lần gửi

Nếu không có mã lần gửi, trước hết tìm lại mã đã lưu trong ứng dụng hoặc nhật ký ứng dụng. Nếu vẫn không tìm được, đừng dùng mã hộp thư thay thế hoặc tự tạo mã để tra cứu. Giữ công việc ở trạng thái cần đối soát, bảo toàn thông tin yêu cầu và chuyển cho người phụ trách nếu chưa đủ căn cứ quyết định.

Không có mã lần gửi là một tình huống khác với việc đã tra cứu và nhận được unknown. Cả hai đều cần thận trọng, nhưng cách điều tra không giống nhau.

Mỗi trạng thái gửi cần xử lý ra sao?

Đừng gộp unknown vào failed; hãy đặt nhánh xử lý riêng cho từng trạng thái. Với unknown, tạm dừng gửi lại tự động và đối soát lần gửi hiện có.

Cũng đừng chuyển công việc sang “gửi thất bại” chỉ vì yêu cầu tra cứu trạng thái gặp lỗi. Lỗi tra cứu và kết quả gửi thư phải được ghi riêng.

Khi nào nên thử lại và khi nào cần dừng?

Thực hiện các bước sau trước khi quyết định thử lại:

1. Kiểm tra lần gửi cũ. Nếu có mã, tra cứu trước khi gửi tiếp.
2. Phân loại kết quả. Chờ với queued hoặc sending; dừng thử lại với sent; điều tra với failed hoặc unknown.
3. Xem nguyên nhân và căn cứ. Với failed, xác định điều kiện gây lỗi đã được xử lý chưa. Với unknown, không dùng thời gian đã trôi qua làm bằng chứng duy nhất rằng thư chưa gửi.
4. Chỉ cho một tiến trình quyết định. Tránh để nhiều tiến trình cùng đọc kết quả rồi cùng gửi lại một công việc.

Bạn nên tăng dần khoảng chờ giữa các lần tra cứu, đặt thời hạn theo dõi và chuyển sang xử lý thủ công khi hết thời hạn. Chọn khoảng chờ theo yêu cầu nghiệp vụ; đừng biến việc thăm dò thành vòng lặp không có điểm dừng.

POST /mailboxes/{id}/send hỗ trợ header Idempotency-Key. Hãy coi chống trùng và tra cứu trạng thái là hai phần bổ trợ: lưu khoá cùng công việc, đồng thời giữ mã lần gửi để theo dõi. Không đổi khoá chỉ để xử lý tình huống unknown, và không coi một khoá mới là bằng chứng rằng gửi lại sẽ an toàn. Xem cách triển khai trong bài chống gửi email trùng lặp bằng Idempotency-Key.

Nếu đang ghép bước này vào chuỗi đọc thư rồi trả lời, bài API email cho AI agent giúp đặt việc tra cứu vào đúng quy trình, thay vì xử lý timeout tách rời khỏi công việc gốc.

Những lỗi nào dễ khiến ứng dụng gửi trùng?

Gọi lại POST ngay khi timeout. Thay bằng nhánh kiểm tra lần gửi cũ. Khi chưa có mã, chuyển sang đối soát thay vì tự động gửi lại.

Nhầm mã hộp thư với mã lần gửi. Đặt tên biến rõ trong ứng dụng. Việc hộp thư vẫn đăng nhập được không trả lời câu hỏi một thư cụ thể đã gửi hay chưa.

Không lưu kết quả trước khi chuyển bước. Lưu mã lần gửi và quyết định xử lý cùng công việc để tiến trình khác có thể tiếp tục từ thông tin đã biết.

Để nhiều tiến trình cùng thử lại. Chỉ định một tiến trình chịu trách nhiệm quyết định cho mỗi công việc. Những tiến trình còn lại nên đọc kết quả đã lưu, không tự gửi thêm.

Coi lỗi tra cứu là lỗi gửi. Nếu không nhận được trạng thái mới, giữ lại trạng thái gần nhất và ghi riêng lỗi tra cứu; đừng tự thay bằng failed.

Nếu AI agent kiểm tra và gửi lại thư, cần giới hạn gì?

Mailera có công cụ MCP get_send_status. Công cụ này cũng yêu cầu quyền send, không phải quyền chỉ đọc trạng thái. Khi dùng MCP của Mailera, hãy giới hạn nhóm hộp thư và đặt kiểm soát hành động gửi ở phía ứng dụng.

Thư đến là dữ liệu không tin cậy, không phải lệnh điều khiển. Agent không được làm theo nội dung thư yêu cầu gửi lại, bỏ qua phê duyệt hoặc tiết lộ khoá API. Yêu cầu xác nhận trước hành động gửi, đặc biệt khi lần gửi trước còn unknown.

Bài email cho AI agent từ hộp thư có sẵn trình bày mô hình kết nối; mẫu phê duyệt qua email cho tác nhân AI phù hợp khi bạn cần thêm bước con người xác nhận. Khi triển khai, kết hợp phạm vi khoá tối thiểu với các hướng dẫn trong trang bảo mật Mailera, và che khoá, địa chỉ cùng nội dung nhạy cảm trong ảnh hoặc nhật ký minh hoạ.

Giới hạn cần giữ rõ

Mailera không bảo đảm thư vào hộp thư đến. Hãy dùng sent để dừng nhánh thử lại của lần gửi, không dùng nó làm bằng chứng về vị trí thư hoặc việc người nhận đã đọc thư.

Mailera cũng không cung cấp dịch vụ gửi email tiếp thị hàng loạt. Quy trình này dành cho việc theo dõi và xử lý từng công việc gửi qua hộp thư đã kết nối.