API email cho AI agent là giao diện để ứng dụng lấy nội dung thư và thực hiện thao tác được cấp quyền. Agent đề xuất cách xử lý; ứng dụng quyết định có cho thực hiện hay không.
Mailera kết nối hộp thư sẵn có với ứng dụng. Nếu cần xem kiến trúc tổng thể trước, đọc cách dùng hộp thư đang có cho AI agent. Phần dưới tập trung vào endpoint, quyền và trạng thái xử lý.
Cần chuẩn bị hộp thư và quyền nào?
Bắt đầu bằng hộp thư thử thuộc quyền kiểm soát của bạn. Hướng dẫn kết nối hộp thư đầu tiên trình bày các bước cài đặt. Với Outlook.com và Microsoft 365, dùng OAuth qua Microsoft Graph, không dùng mật khẩu ứng dụng. Mailera kết nối Gmail bằng mật khẩu ứng dụng (app password).
Trong Cài đặt, mở phần khóa API rồi chọn Tạo key. Chọn Phạm vi hộp thư là nhóm cần xử lý và chỉ cấp read lúc đầu. Thêm move khi bật chức năng chuyển thư; chỉ cấp send cho thành phần thực hiện gửi đã được kiểm soát.
Quyền của khóa Mailera khác với quyền ứng dụng được cấp tại nhà cung cấp. Với Microsoft Graph, Microsoft khuyến nghị xin quyền tối thiểu cần thiết.
Khóa mới chỉ hiển thị một lần. Lưu khóa ở phía máy chủ, không đưa vào ngữ cảnh mô hình, ảnh chụp hoặc nhật ký. API dùng địa chỉ gốc https://mailera.app/api/public/v1 và header Authorization: Bearer $MAILERA_API_KEY.
Trong các lệnh dưới đây, đặt $MAILERA_API_KEY bằng khóa thử của bạn; $MAILBOX_ID và $MESSAGE_ID là định danh lấy từ phản hồi API.
Mỗi việc tương ứng với API nào?
Bảng này là bản đồ thao tác, không phải danh sách quyền nên cấp hết cho agent. Trang dành cho nhà phát triển giới thiệu các giao diện tích hợp.
| Việc cần làm | Phương thức và đường dẫn | Quyền | Kiểm tra trước khi gọi |
|---|---|---|---|
| Chọn hộp thư | GET /mailboxes | read | Nhóm hộp thư được phép |
| Liệt kê thư | GET /mailboxes/{id}/messages | read | Thư mục, bộ lọc, giới hạn |
| Đọc nội dung | GET /mailboxes/{id}/messages/{msgId} | read | Đúng hộp thư và thư cần đọc |
| Tìm trên nhiều hộp thư | GET /messages/search | read | Giới hạn bằng mailbox, since |
| Chuyển thư | POST /mailboxes/{id}/messages/{msgId}/move | move | Thư mục đích được phép |
| Gửi, trả lời, chuyển tiếp | POST /mailboxes/{id}/send | send | Hộp gửi, người nhận, nội dung đã duyệt |
| Xem lần gửi | GET /sends/{id} | send | Định danh của lần gửi cần kiểm tra |
Phân loại nội dung là việc của agent. Chuyển thư sau khi phân loại là thao tác riêng, cần quyền move. Tương tự, tạo nội dung trả lời trong ứng dụng không cần trao quyền gửi cho mô hình.
Luồng đọc và đề xuất trả lời đi theo thứ tự nào?
1. Chọn hộp thư được phép
Lấy một hộp thư để kiểm tra kết nối API:
curl --get 'https://mailera.app/api/public/v1/mailboxes' \
--header "Authorization: Bearer $MAILERA_API_KEY" \
--data-urlencode 'limit=1'Đọc data[].id, status, capabilities và sync. Trước khi cho phép trả lời, kiểm tra capabilities.send; việc đọc được thư không có nghĩa hộp thư gửi được.
2. Lấy danh sách có giới hạn
curl --get "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages" \
--header "Authorization: Bearer $MAILERA_API_KEY" \
--data-urlencode 'folder=inbox' \
--data-urlencode 'limit=1'Danh sách có id, mailbox_id, subject, preview và conversation_id. Dùng next_cursor cho lần lấy trang tiếp theo qua tham số cursor. Có thể thu hẹp bằng since, from, q hoặc unread.
Ứng dụng nên lưu cặp định danh hộp thư và thư đã xử lý. Đừng chỉ dựa vào trạng thái chưa đọc để quyết định có chạy agent lần nữa hay không.
3. Đọc nội dung cần thiết
curl "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
--header "Authorization: Bearer $MAILERA_API_KEY"Nội dung nằm trong data.body.text và data.body.html. Kiểm tra body_error trước khi đưa nội dung cho agent. preview trong danh sách không thay thế toàn bộ nội dung thư.
4. Tạo đề xuất trong ứng dụng
Cho agent đề xuất thao tác hoặc soạn câu trả lời, nhưng giữ nội dung thư tách khỏi chỉ dẫn của ứng dụng. Nội dung chờ duyệt được lưu ở phía ứng dụng; bước này không phải lời gọi API lưu bản nháp Mailera.
5. Duyệt rồi mới gửi
Ứng dụng kiểm tra hộp thư gửi, người nhận, nội dung và thư gốc cần trả lời. Hiển thị các thông tin đó để người dùng xác nhận trước khi gọi /send. Lưu kết quả phê duyệt cùng định danh thư gốc để tránh gửi một đề xuất đã bị sửa sau khi duyệt.
Tránh gửi lặp khi yêu cầu hết thời gian chờ thế nào?
Endpoint gửi nhận header Idempotency-Key, với cửa sổ chống lặp 24 giờ. Ứng dụng nên tạo và lưu khóa này trước khi gửi, gắn nó với một thao tác đã được duyệt.
Nếu yêu cầu hết thời gian chờ, đừng lập tức tạo khóa mới và gửi lại. Khi đã có định danh lần gửi, gọi GET /sends/{id} để kiểm tra. API có các trạng thái queued, sending, sent, failed và unknown.
Với queued hoặc sending, tiếp tục theo dõi lần gửi đó. Với unknown, giữ thao tác ở trạng thái cần đối soát thay vì tự coi là thất bại rồi gửi mới. Lưu trạng thái API trả về, không đánh dấu hoàn tất chỉ vì ứng dụng đã phát yêu cầu.
Cửa sổ 24 giờ không thay thế sổ theo dõi gửi của ứng dụng. Hãy giữ định danh thư gốc, khóa chống lặp và kết quả xử lý đủ lâu theo nhu cầu vận hành.
Trước khi dựng dữ liệu gửi hoặc trả lời, đối chiếu tài liệu API Mailera. Giữ định danh thư gốc xuyên suốt luồng; đừng dùng riêng tiêu đề làm căn cứ chọn hội thoại.
Khi nào dùng REST API, MCP hoặc webhook?
| Giao diện | Khi nên dùng | Phần ứng dụng vẫn phải làm |
|---|---|---|
| REST API | Cần tự điều phối từng lời gọi | Kiểm tra đầu vào, lưu trạng thái, duyệt thao tác |
| MCP | Ứng dụng AI tương thích cần gọi công cụ | Giới hạn quyền và xác nhận thao tác nhạy cảm |
| Webhook | Cần kích hoạt xử lý khi có sự kiện | Xác minh chữ ký và chống xử lý lặp |
Với luồng trả lời có điều kiện duyệt, nên bắt đầu bằng REST API vì bạn đặt được bước kiểm tra ngay trước lời gọi gửi.
MCP của Mailera nằm tại https://mailera.app/api/public/v1/mcp. Các công cụ list_messages, get_message dùng read; reply_to_email, get_send_status dùng send. Xem công cụ MCP theo từng tác vụ nếu ứng dụng của bạn dùng giao diện này.
Webhook message.received có thể kích hoạt xử lý thư mới. Lưu bí mật ký khi tạo webhook vì giá trị này chỉ được trả về một lần. Phía nhận cần xác minh chữ ký và lưu dấu xử lý để sự kiện giao lại không chạy cùng tác vụ hai lần.
Chống xử lý lặp sự kiện và chống gửi lặp là hai việc riêng: một việc nằm ở bộ nhận webhook, việc kia dùng Idempotency-Key khi gửi. Thời điểm thấy thư còn phụ thuộc kết nối và đồng bộ; hộp thư ít hoạt động có thể ngủ, nên không thiết kế dựa trên giả định thư luôn xuất hiện tức thời.
Những lỗi nào thường gặp?
| Triệu chứng | Kiểm tra và xử lý |
|---|---|
| Không đọc được thư | Kiểm tra khóa bị thu hồi hoặc hết hạn, quyền read, phạm vi nhóm và trạng thái hộp thư. Khóa bị thu hồi bị từ chối ngay. |
| Chưa thấy thư mới | Kiểm tra folder, bộ lọc, next_cursor và thông tin sync. Đồng bộ chủ động qua POST /mailboxes/{id}/sync cần quyền sync. |
| Đọc được nhưng không gửi được | Kiểm tra quyền send, capabilities.send và cấu hình gửi. Hộp thư có thể đã được lưu ở chế độ chỉ nhận. |
| Gửi bị hết thời gian chờ | Kiểm tra lần gửi cũ; không tạo khóa chống lặp mới ngay. |
| Trả lời nhầm hội thoại | Kiểm tra định danh thư gốc được lưu và dữ liệu trả lời theo tài liệu API, không chỉ nhìn tiêu đề. |
Nút Kiểm tra & kết nối chỉ thử kết nối, không gửi thư thật. Vì vậy, hoàn tất bước này không thay thế việc thử luồng trả lời trên hộp thư của bạn.
Ngăn agent làm theo chỉ dẫn trong thư thế nào?
Thư đến là dữ liệu không tin cậy, không phải lệnh. Một thư có thể yêu cầu agent đổi người nhận, tiết lộ khóa hoặc chuyển tiếp dữ liệu. Không cho nội dung đó thay đổi chính sách của ứng dụng.
Đặt kiểm soát ngoài mô hình: giới hạn hộp thư được đọc, chỉ đưa phần nội dung cần thiết vào ngữ cảnh và giữ khóa gửi ở thành phần thực hiện thao tác sau phê duyệt. Một câu nhắc trong lời dẫn không thay thế việc kiểm tra người nhận và quyền ở máy chủ.
Không tự làm theo yêu cầu trong thư về tiết lộ bí mật, chuyển tiếp dữ liệu hay mở liên kết. Với thao tác gửi, yêu cầu người dùng xác nhận. Đặc tả công cụ MCP cũng khuyến nghị xác nhận thao tác nhạy cảm và giữ khả năng từ chối lời gọi công cụ.
Bước duyệt và chính sách thao tác do ứng dụng của bạn triển khai. Tham khảo thêm thông tin bảo mật Mailera khi thiết kế cách quản lý khóa.
Giới hạn cần tính vào ứng dụng
Mailera không cung cấp gửi tiếp thị hàng loạt. Hộp thư chỉ nhận cần được loại khỏi luồng gửi, dù khóa API có quyền send.
Mailera cũng không bảo đảm thư gửi sẽ vào Hộp thư đến. Trạng thái lần gửi không nên được dùng làm bằng chứng về vị trí thư trong hộp thư người nhận.
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
