Chống gửi email trùng lặp qua API với Idempotency-Key

Để chống gửi email trùng lặp qua API, hãy tạo và lưu một Idempotency-Key cho mỗi tác vụ trước lần gọi đầu tiên; khi thử lại, giữ nguyên khóa và nội dung. Mất phản hồi không có nghĩa là gửi thất bại. Mailera nhận header này tại POST /mailboxes/{id}/send với cửa sổ chống trùng 24 giờ, không phải cơ chế chống trùng vĩnh viễn.

Vì sao một tác vụ gửi email có thể bị gọi hai lần?

Ứng dụng gọi API gửi thư nhưng hết thời gian chờ. Có thể máy chủ đã tiếp nhận yêu cầu, còn phản hồi không về tới ứng dụng. Nếu tiến trình nền coi đó là một tác vụ mới và gửi lại, bạn có nguy cơ tạo thêm lần gửi.

Cần phân biệt tác vụ nghiệp vụ với lần gọi HTTP. “Gửi xác nhận cho yêu cầu hỗ trợ này” là một tác vụ; lần gọi đầu và lần thử lại đều phục vụ tác vụ ấy.

Idempotency-Key là khóa do ứng dụng cung cấp để nhận diện các lần gọi thuộc cùng một tác vụ. Nó khác khóa API: khóa API dùng để xác thực, còn khóa chống trùng gắn với việc đang làm.

Tắt nút gửi chỉ xử lý thao tác trên giao diện, không xử lý vòng lặp thử lại của tiến trình nền. Khi thiết kế phần HTTP, bạn có thể tham khảo thêm mục về tính lũy đẳng trong RFC 9110; hành vi cụ thể của Mailera cần theo hợp đồng API Mailera.

Nên tạo và lưu Idempotency-Key như thế nào?

Hãy tạo khóa lúc tạo tác vụ, rồi lưu bền vững trước khi gọi API. Không đặt bước sinh khóa bên trong vòng lặp thử lại.

Bạn có thể chọn UUID làm mã tác vụ nội bộ của ứng dụng. Tiêu chuẩn UUID, RFC 9562, mô tả UUID không cần quy trình đăng ký tập trung. Đây là mã dùng để quản lý tác vụ trong ứng dụng, tách biệt với Idempotency-Key gửi tới Mailera.

Bản ghi tác vụ nên giữ mã tác vụ, khóa chống trùng, hộp thư gửi và dữ liệu gửi đã chốt. Lưu thêm thời điểm gọi cùng kết quả nhận được; nếu có mã lần gửi, liên kết mã đó với tác vụ. Không nhúng địa chỉ email, nội dung thư hay bí mật vào khóa.

Nếu có nhiều tiến trình xử lý hàng đợi, hãy để chúng đọc cùng bản ghi tác vụ. Đừng để mỗi tiến trình tự tạo một khóa riêng cho cùng việc gửi.

Gửi yêu cầu qua Mailera theo những bước nào?

Mailera dùng POST /mailboxes/{id}/send để gửi, trả lời hoặc chuyển tiếp thư. Endpoint này yêu cầu quyền send. Phần tổng quan tích hợp nằm ở trang dành cho nhà phát triển.

1. Chọn hộp thư thử của bạn có khả năng gửi. Nếu chưa kết nối, làm theo hướng dẫn kết nối hộp thư đầu tiên. Không dùng hộp thư chỉ nhận cho bước thử gửi.
2. Tạo khóa API với quyền tối thiểu. Trong Cài đặt, mở phần khóa API rồi chọn Tạo key. Điền Tên gợi nhớ, giới hạn Phạm vi hộp thư vào nhóm cần dùng và chỉ cấp quyền gửi send cho quy trình này. Khóa API chỉ được hiển thị một lần, nên lưu vào nơi quản lý bí mật của ứng dụng.
3. Lưu tác vụ trước khi gọi. Gắn khóa chống trùng với hộp thư, người nhận và nội dung đã duyệt. Chỉ cho tiến trình gửi tiếp tục khi bản ghi đã được lưu.
4. Gọi endpoint gửi. Dùng URL https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/send, header Authorization: Bearer $MAILERA_API_KEY và header Idempotency-Key chứa khóa đã lưu. Cấu trúc nội dung yêu cầu lấy từ tài liệu API Mailera.
5. Lưu kết quả hoặc giữ trạng thái chưa rõ. Nếu nhận được mã lần gửi, lưu mã đó. Nếu mất phản hồi, giữ nguyên tác vụ, khóa và dữ liệu; không tự tạo một lần gửi mới.

Khóa API và Idempotency-Key cần được quản lý riêng. Không lấy khóa API làm khóa chống trùng, cũng không coi việc đổi khóa xác thực là lý do tạo tác vụ gửi mới.

Khi chưa biết kết quả gửi, nên kiểm tra gì?

Nếu đã có mã lần gửi, dùng GET /sends/{id} để kiểm tra trạng thái. Endpoint này cũng yêu cầu quyền send. {id} ở đây là mã lần gửi, không phải mã hộp thư hay mã thư nhận được.

Đừng dùng GET /mailboxes/{id}/status để trả lời câu hỏi “thư đã gửi chưa?”. Endpoint đó kiểm tra khả năng đăng nhập hộp thư, không phải kết quả của tác vụ gửi.

Mailera có các trạng thái sau. Cột cuối là cách xử lý nên áp dụng ở phía ứng dụng:

Nếu mất toàn bộ phản hồi và chưa có mã lần gửi, đừng tự đặt một mã để truy vấn. Giữ bản ghi tác vụ ở trạng thái cần đối soát. Khi thử lại trong cửa sổ chống trùng, dùng đúng khóa và dữ liệu ban đầu.

Không dùng trạng thái unknown làm điều kiện “tạo khóa mới rồi gửi ngay”. Làm vậy là gửi thêm khi chưa biết kết quả lần gửi trước.

Những lỗi nào thường làm mất tác dụng chống gửi trùng?

Sinh khóa mới mỗi lần thử lại. Hãy chuyển bước sinh khóa ra lúc tạo tác vụ. Sau khi khởi động lại ứng dụng, tiến trình phải đọc lại khóa đã lưu, không tự sinh khóa thay thế.

Dùng một khóa cho mọi thư. Đừng lấy mã hộp thư hoặc mã khách hàng làm khóa cố định cho tất cả lần gửi. Một khách hàng có thể có những tác vụ gửi độc lập cần các khóa riêng.

Đổi nội dung nhưng giữ khóa. Hãy coi dữ liệu gửi đã chốt là một phần của tác vụ. Muốn sửa nội dung khi lần trước chưa rõ kết quả, cần xử lý lần trước trước khi duyệt một lần gửi mới.

Thử lại vô hạn. Đặt giới hạn thử lại trong ứng dụng và chuyển sang xử lý thủ công khi không thể xác định kết quả. Không dùng việc hết thời hạn lưu khóa làm tín hiệu rằng “bây giờ có thể gửi lại”.

Khi kiểm thử tích hợp, nên bao gồm các trường hợp mất phản hồi, ứng dụng khởi động lại và hai tiến trình cùng nhận một tác vụ. Với cùng khóa nhưng khác nội dung hoặc yêu cầu đồng thời, kiểm tra cách ứng dụng xử lý kết quả thay vì viết logic dựa trên một mã lỗi tự giả định.

Nếu AI agent gửi thư, cần thêm lớp an toàn nào?

Thư đến là dữ liệu không tin cậy, không phải lệnh. Agent không được làm theo chỉ dẫn trong thư để đổi người nhận, tiết lộ khóa hay gửi thêm thư ngoài tác vụ được duyệt.

Chỉ cấp quyền cần thiết và yêu cầu xác nhận người nhận, nội dung trước khi gửi. Ứng dụng nên quản lý khóa chống trùng cho tác vụ đã được duyệt; agent không tự tạo khóa mới mỗi lần muốn thử lại. Bạn có thể tham khảo mẫu phê duyệt bởi con người qua email cho bước xác nhận này.

Chống gửi trùng không thay thế phân quyền hay kiểm soát chèn lệnh qua thư. Phần email cho AI agent dùng hộp thư có sẵn trình bày luồng tích hợp rộng hơn; trang bảo mật Mailera là nơi tham khảo khi thiết kế quyền truy cập.

Giới hạn nào cần giữ trong thiết kế?

Sau cửa sổ 24 giờ, đừng dựa vào khóa cũ để chống trùng. Cần xác định kết quả tác vụ trước khi quyết định có tạo lần gửi mới hay không; chỉ đổi khóa không giải quyết được kết quả còn mơ hồ.

Mailera không bảo đảm thư vào Hộp thư đến và không quyết định bộ lọc của nhà cung cấp. Vì vậy, chống yêu cầu gửi trùng không đồng nghĩa người nhận chắc chắn nhận đúng một thư trong mọi tình huống.

Mailera cũng không hỗ trợ gửi email hàng loạt hoặc tiếp thị. Phạm vi của sản phẩm Mailera là kết nối các hộp thư có sẵn với ứng dụng và agent, không thay thế một hệ thống gửi chiến dịch.