---
title: "Kiểm tra trạng thái gửi email qua API trước khi thử lại"
description: "Dùng GET /sends/{id} để kiểm tra trạng thái gửi email qua API sau timeout. Phân biệt queued, sending, sent, failed và unknown trước khi quyết định gửi lại."
url: https://mailera.app/blog/kiem-tra-trang-thai-gui-email-qua-api
published: 2026-10-25
updated: 2026-10-25
---

# 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ờ không có nghĩa là thư chưa gửi. Tra cứu lần gửi cũ bằng GET /sends/{id}, rồi quyết định chờ, dừng hay đối soát trước khi gửi 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:

| Lớp thông tin | Câu hỏi cần trả lời |
| --- | --- |
| Phản hồi HTTP | Ứng dụng có nhận được phản hồi cho yêu cầu không? |
| Trạng thái lần gửi tại Mailera | Lần gửi đang chờ, đang chạy hay đã có kết quả? |
| Kết quả phía người nhận | Thư đã tới đâu, có nằm trong hộp thư đến không? |

Ví dụ, [tài liệu Microsoft Graph sendMail](https://learn.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0) 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](https://www.rfc-editor.org/rfc/rfc5321.html) 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](https://mailera.app/product) với ứng dụng. Trong [REST API của Mailera](https://mailera.app/developers), 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ý.

![Hộp thoại tạo khoá API với phạm vi một nhóm hộp thư và quyền send](https://mailera.app/media/1643f007f3cf2e3c/kiem-tra-trang-thai-gui-email-qua-api-truoc-khi-thu-lai-api-vi-1200.jpg)
_Tra cứu trạng thái lần gửi cần quyền send; giới hạn khoá vào nhóm hộp thư phục vụ công việc._

### 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](https://mailera.app/docs). 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?

| Trạng thái | Cách hiểu để xử lý | Hành động đề xuất | Chưa thể kết luận |
| --- | --- | --- | --- |
| `queued` | Lần gửi đang chờ | Theo dõi lần gửi hiện có | Thư đã được gửi đi |
| `sending` | Lần gửi đang thực hiện | Chờ rồi kiểm tra lại có giới hạn | Cần gửi thêm một bản |
| `sent` | Lần gửi được ghi nhận là đã gửi | Dừng nhánh thử lại của công việc | Thư vào hộp thư đến hoặc đã được đọc |
| `failed` | Lần gửi được ghi nhận là thất bại | Xem nguyên nhân trước khi quyết định | Mọi lỗi đều có thể thử lại ngay |
| `unknown` | Kết quả chưa xác định | Tạm dừng gửi lại tự động, đối soát | Thư chắc chắn chưa được gửi |

![Tra cứu mã lần gửi rồi chọn chờ, dừng thử lại, xem nguyên nhân hoặc đối soát theo trạng thái](https://mailera.app/media/c8148833eacdeae2/kiem-tra-trang-thai-gui-email-qua-api-truoc-khi-thu-lai-vi-1200.jpg)
_Chính sách xử lý đề xuất: unknown đi vào nhánh đối soát, không đi thẳng tới gửi lại._

Đừ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](https://mailera.app/blog/chong-gui-email-trung-lap-qua-api).

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](https://mailera.app/blog/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](https://mailera.app/mcp), 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](https://mailera.app/blog/ket-noi-email-voi-ai) trình bày mô hình kết nối; mẫu [phê duyệt qua email cho tác nhân AI](https://mailera.app/blog/phe-duyet-qua-email-cho-tac-nhan-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](https://mailera.app/security), 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.

**Làm điều này bằng API** — Mọi thao tác trong bài đều có REST API kèm ví dụ curl, khoá API và webhook. [Xem tài liệu API](https://mailera.app/docs)