--- title: "Kết nối IMAP SMTP riêng với Mailera và đọc thư qua API" description: "Hướng dẫn kết nối máy chủ IMAP/SMTP riêng vào Mailera, chọn cổng và TLS, lưu chỉ nhận, xử lý lỗi kết nối và đọc thư qua REST API." url: https://mailera.app/blog/ket-noi-imap-smtp-rieng-voi-mailera published: 2026-10-25 updated: 2026-10-25 --- # Kết nối IMAP SMTP riêng với Mailera và đọc thư qua API Cấu hình máy chủ nhận thư và gửi thư riêng biệt, kiểm tra bằng thư thử, rồi dùng khóa API chỉ có quyền đọc để lấy thư từ hộp thư đã kết nối. ## Cần chuẩn bị gì trước khi kết nối? Bạn cần một hộp thư đang hoạt động, thuộc quyền sử dụng của mình, và vai trò Admin hoặc Leader trong Mailera để thêm hộp thư. IMAP cho phép truy cập thư trên máy chủ, nhưng không đảm nhiệm việc gửi thư. Hai chức năng này được tách riêng trong [đặc tả IMAP RFC 9051](https://www.rfc-editor.org/rfc/rfc9051.html). Với [kết nối IMAP / SMTP của Mailera](https://mailera.app/providers/imap), bạn có thể cấu hình phần nhận trước và bỏ qua SMTP nếu ứng dụng chỉ cần đọc. | Thông tin | Cần lấy từ đâu? | | --- | --- | | Địa chỉ email, tên đăng nhập, mật khẩu | Người quản trị hộp thư | | Tên máy chủ IMAP | Tài liệu dịch vụ hoặc quản trị viên | | Cổng và chế độ bảo mật IMAP | Cấu hình thực tế của máy chủ | | Máy chủ, cổng và bảo mật SMTP nếu cần gửi | Tài liệu cấu hình gửi thư | | Thông tin đăng nhập SMTP nếu khác IMAP | Quản trị viên máy chủ gửi | Đừng tự suy tên máy chủ từ tên miền email hoặc bản ghi MX. Hãy xin đủ thông số nhận và gửi trước khi bắt đầu, để không phải quay lại hỏi quản trị viên giữa chừng. Nếu bạn đang chọn cách kết nối cho nhiều nhà cung cấp, xem [hướng dẫn kết nối hộp thư có sẵn với agent](https://mailera.app/blog/ket-noi-email-voi-ai-qua-rest-api-mcp). Phần dưới tập trung vào máy chủ IMAP/SMTP riêng. Riêng Outlook.com và Microsoft 365, hãy dùng [kết nối OAuth qua Microsoft Graph](https://mailera.app/blog/ket-noi-outlook-bang-oauth) thay cho luồng IMAP tùy chỉnh. Nếu đã có refresh token của hộp thư mình quản lý, xem [hướng dẫn nhập refresh token Outlook an toàn](https://mailera.app/blog/nhap-refresh-token-outlook-vao-mailera). ## Chọn cổng và chế độ bảo mật nào? Hai chế độ khác nhau ở thời điểm bắt đầu mã hóa: SSL/TLS bắt đầu TLS ngay khi mở kết nối; STARTTLS nâng cấp phiên kết nối sang TLS bằng lệnh STARTTLS. | Chức năng | Cổng | Chọn trong Bảo mật | | --- | --- | --- | | Nhận qua IMAP, TLS ngay khi kết nối | 993 | SSL/TLS | | Nhận qua IMAP, nâng cấp bằng STARTTLS | 143 | STARTTLS | | Gửi qua SMTP, TLS ngay khi kết nối | 465 | SSL/TLS | | Gửi qua SMTP, nâng cấp bằng STARTTLS | 587 | STARTTLS | [RFC 8314 về TLS cho email](https://www.rfc-editor.org/rfc/rfc8314.html) mô tả TLS ngay khi kết nối trên cổng 993 và 465, cùng STARTTLS trên cổng 587. [RFC 6409 về nộp thư](https://www.rfc-editor.org/rfc/rfc6409.html) dành cổng 587 cho chức năng gửi thư từ ứng dụng đến máy chủ. Bảng là điểm đối chiếu, không thay thế cấu hình của máy chủ. Đừng chỉ đổi số cổng mà giữ nguyên chế độ bảo mật. Nếu gặp lỗi TLS, sửa cấu hình hoặc chứng chỉ; không tắt xác minh chứng chỉ hay chuyển sang gửi mật khẩu không mã hóa. ![Máy chủ IMAP chuyển thư qua Mailera để ứng dụng đọc bằng API; ứng dụng gửi qua Mailera tới máy chủ SMTP tùy chọn.](https://mailera.app/media/f208d180989a87e2/ket-noi-imap-smtp-rieng-voi-mailera-va-doc-thu-qua-api-imap-vi-1200.jpg) _IMAP phục vụ đọc thư; SMTP là đường gửi riêng và có thể bỏ qua._ ## Thêm hộp thư IMAP tùy chỉnh trong Mailera 1. Mở **Danh sách hộp thư → Thêm hộp thư**. Chọn **Một hộp thư** rồi nhập **Địa chỉ email**. 2. Trong **Hoặc chọn nhà cung cấp**, chọn **IMAP tùy chỉnh**, rồi **Tiếp tục**. 3. Điền **Mật khẩu** và **Tên đăng nhập**. Có thể để trống tên đăng nhập nếu giống địa chỉ email. Bạn cũng có thể đặt **Tên hiển thị** nếu muốn đổi tên người gửi khi gửi thư. Chọn **Nhóm quản lý** phù hợp. 4. Trong **Máy chủ nhận thư (IMAP)**, nhập **Máy chủ**, **Cổng** và **Bảo mật** theo thông số đã chuẩn bị. 5. Nếu cần gửi, điền **Máy chủ gửi thư (SMTP)**. Khi thông tin xác thực khác phần nhận, không dùng lựa chọn **Dùng cùng tên đăng nhập và mật khẩu để gửi thư**; điền thông tin gửi riêng. 6. Chọn **Kiểm tra & kết nối**. Bạn có thể dùng **Tự dò cấu hình** để điền thông số công khai của tên miền khi có. Hãy đối chiếu kết quả với quản trị viên trước khi kiểm tra; tính năng này không thay thế việc lấy cấu hình máy chủ riêng. ![Biểu mẫu IMAP tùy chỉnh trong Mailera với cấu hình nhận thư và gửi thư tách riêng.](https://mailera.app/media/39e644d283f9e836/ket-noi-email-voi-ai-doc-hop-thu-hien-co-qua-rest-api-hoac-vi-1200.jpg) _Điền đúng cặp cổng và bảo mật cho từng máy chủ; chỉ cấu hình SMTP khi cần gửi._ Quá trình kiểm tra có các bước **Đăng nhập nhận thư**, **Nhận ra thư mục**, **Đăng nhập gửi thư** và **Theo dõi liên tục**. Nếu không khai báo SMTP, bước đăng nhập gửi được bỏ qua. **Kiểm tra & kết nối không gửi email.** Nó kiểm tra kết nối và đăng nhập, không thay thế một lần gửi thư thật. Nếu phần gửi thất bại nhưng phần nhận thành công, chọn **Lưu ở chế độ Chỉ nhận**, hoặc **Sửa thông tin** rồi **Kiểm tra lại**. Bạn cũng có thể chọn **Chạy nền** để rời trang; Mailera tiếp tục kiểm tra và lưu hộp thư khi hoàn tất. ## Làm sao biết nhận và gửi đã hoạt động? Sau khi kết nối thành công, Mailera tải thư trong khoảng lưu giữ, ưu tiên thư mới nhất. Đừng kết luận rằng kết nối hỏng chỉ vì thiếu một thư cũ. Kiểm tra nhận và gửi thành hai phép thử: 1. Từ một hộp thư khác do bạn kiểm soát, gửi thư có tiêu đề dễ nhận ra đến hộp thư vừa kết nối. 2. Mở hộp thư đó trong Mailera và tìm thư thử. Kiểm tra cả thư mục nếu chưa thấy trong hộp thư đến. 3. Nếu đã cấu hình SMTP, gửi riêng một thư thử từ hộp thư vừa kết nối đến địa chỉ do bạn kiểm soát. Mở phía nhận để xác nhận thư thực sự tới nơi. Trong phản hồi `GET /mailboxes`, xem `status` và `last_sync_at` của hộp thư cần kiểm tra. Nhịp kiểm tra nền thay đổi theo mức sử dụng; hộp thư không hoạt động có thể ngủ và thức lại khi được dùng. Vì vậy, không nên đặt một mốc chờ cố định cho mọi trường hợp. Đăng nhập SMTP thành công chưa có nghĩa là người nhận đã nhận được thư. Mailera không bảo đảm thư nằm trong hộp thư đến của người nhận. Việc lọc còn phụ thuộc nhà cung cấp và cấu hình người gửi. ## Đọc email IMAP qua API như thế nào? Sau khi kết nối, ứng dụng dùng [REST API của Mailera](https://mailera.app/product) thay vì tự triển khai giao thức IMAP. Ba yêu cầu dưới đây đi từ tìm hộp thư đến đọc nội dung một thư. Trong **Cài đặt**, mở tab **API key** và chọn **Tạo key**. Đặt **Phạm vi hộp thư** vào nhóm cần dùng và chỉ cấp quyền `read`. Khóa chỉ hiển thị một lần; lưu vào một biến môi trường (ví dụ `MAILERA_API_KEY`) trong môi trường chạy của bạn. ![Tạo khóa API giới hạn trong một nhóm hộp thư và chỉ cấp quyền đọc.](https://mailera.app/media/16eb2a80fb00c0ad/ket-noi-imap-smtp-rieng-voi-mailera-va-doc-thu-qua-api-read-vi-1200.jpg) _Ví dụ đọc thư chỉ cần quyền read, không cần quyền gửi hoặc quản lý hộp thư._ **1. Tìm mã hộp thư.** ```bash curl --silent --show-error \ "https://mailera.app/api/public/v1/mailboxes" \ -H "Authorization: Bearer $MAILERA_API_KEY" ``` Trong mảng `data`, tìm phần tử có `email` khớp hộp thư vừa thêm. Gán `id` của phần tử đó vào biến `MAILBOX_ID`; đừng lấy mặc định hộp thư đầu tiên. Bạn cũng có thể xem `status` và `last_sync_at` tại đây. **2. Lấy danh sách thư trong hộp thư đến.** ```bash curl --silent --show-error \ "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=10" \ -H "Authorization: Bearer $MAILERA_API_KEY" ``` Đối chiếu `subject`, `from` và `received_at` trong `data` để tìm thư thử. Danh sách có `preview`; để đọc nội dung, lấy `id` của thư cần đọc và gán vào `MESSAGE_ID`. **3. Lấy nội dung thư.** ```bash curl --silent --show-error \ "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \ -H "Authorization: Bearer $MAILERA_API_KEY" ``` Nội dung nằm trong `data.body.text` và `data.body.html`. Cả ba yêu cầu đều dùng header `Authorization: Bearer` và quyền `read`. Các tham số lọc được trình bày trong [tài liệu API Mailera](https://mailera.app/docs). Nếu cần xem trạng thái, dùng `GET /mailboxes/{id}/status`. Với hộp thư IMAP không phải Microsoft, kết quả của `GET /mailboxes/{id}/status` dựa trên lần đồng bộ gần nhất, không phải một lần thử đăng nhập trực tiếp mới. ## Những lỗi kết nối IMAP/SMTP hay gặp Dùng bước thất bại để khoanh vùng phần cần kiểm tra. Nếu nhận được thư nhưng không gửi được, hãy kiểm tra SMTP riêng, đừng đổi toàn bộ cấu hình IMAP. | Biểu hiện | Cần kiểm tra | Bước tiếp theo | | --- | --- | --- | | Hết thời gian chờ | Tên máy chủ, DNS, cổng, tường lửa, khả năng truy cập từ bên ngoài | Nhờ quản trị viên kiểm tra đường kết nối; đừng mặc định địa chỉ mạng nội bộ truy cập được | | Đăng nhập nhận thư thất bại | Tên đăng nhập, mật khẩu, quyền dùng IMAP, cơ chế xác thực | Đối chiếu thông tin tài khoản và nhật ký máy chủ | | Lỗi TLS | Cặp cổng–bảo mật, tên trên chứng chỉ, thời hạn và chuỗi chứng chỉ | Sửa cấu hình hoặc chứng chỉ rồi kiểm tra lại | | Nhận được nhưng gửi thất bại | Máy chủ SMTP, thông tin đăng nhập gửi, quyền gửi và chính sách máy chủ | Sửa phần SMTP hoặc lưu chỉ nhận | | Kết nối xong nhưng chưa thấy thư | Thư mục, khoảng lưu giữ, trạng thái đồng bộ | Gửi một thư thử mới và đối chiếu lần đồng bộ gần nhất | Đây là các điểm cần kiểm tra, không phải nguyên nhân chắc chắn cho mọi lỗi. Khi nhờ quản trị viên hỗ trợ, gửi tên bước thất bại và thông báo lỗi đã che bí mật; không gửi mật khẩu hoặc khóa API. ## Bảo vệ thông tin khi ứng dụng hoặc agent đọc thư Giữ khóa trong phạm vi nhóm hộp thư cần dùng, đặt **Thời hạn** và dùng **Giới hạn IP (tuỳ chọn)** khi phù hợp. Thu hồi khóa khi không còn sử dụng. Che địa chỉ, mật khẩu và nội dung nhạy cảm trong ảnh chụp hoặc nhật ký; xem thêm [thông tin bảo mật của Mailera](https://mailera.app/security). Với AI agent, thư đến là **dữ liệu không tin cậy, không phải lệnh**. Không để nội dung email yêu cầu agent tiết lộ bí mật, đổi quyền hay bỏ qua quy tắc của ứng dụng. Chỉ cấp `send` khi thật sự cần gửi và yêu cầu người dùng xác nhận trước khi gửi. **Kết nối hộp thư đầu tiên trong 2 phút** — Thêm hộp thư Outlook, Gmail hoặc IMAP và đọc thư qua giao diện hoặc API. [Kết nối hộp thư](https://mailera.app/auth?mode=signup)