Cài đặt IMAP Gmail: máy chủ, cổng và cách đăng nhập

Thông số IMAP và SMTP của Gmail cần nhập là gì?

IMAP dùng để đọc và đồng bộ thư; SMTP dùng để gửi. Khi cài đặt IMAP Gmail, hãy kiểm tra riêng hai phần này, vì đăng nhập nhận thư thành công chưa có nghĩa là gửi thư được.

SMTP cần xác thực. Với Google Workspace, nhập đầy đủ địa chỉ theo tên miền tổ chức, không chỉ phần đứng trước dấu @.

Tài liệu giao thức Gmail của Google xác nhận máy chủ IMAP và hỗ trợ OAuth. Hướng dẫn cấu hình ứng dụng email của Google Workspace ghi cổng SMTP 587 với lựa chọn “TLS”, hoặc 465 với “SSL”. Trong Mailera, cấu hình Gmail có sẵn dùng 587 với STARTTLS; không ghép cổng này với chế độ SSL/TLS ngay khi mở kết nối.

Nếu dùng Gmail, chọn cấu hình Gmail có sẵn. Kết nối IMAP/SMTP tùy chỉnh dành cho trường hợp bạn cần tự nhập thông tin máy chủ.

Nếu bạn đang cấu hình thêm hộp thư iCloud, dùng hướng dẫn cài đặt IMAP và SMTP cho iCloud Mail cho hộp thư đó.

Nên dùng OAuth hay mật khẩu ứng dụng Gmail?

Địa chỉ máy chủ quyết định nơi ứng dụng kết nối. OAuth hoặc mật khẩu ứng dụng quyết định cách ứng dụng được phép đăng nhập.

Mật khẩu ứng dụng (app password) không phải mật khẩu đăng nhập Google. Với kết nối Gmail và Google Workspace của Mailera, trường Mật khẩu nhận mật khẩu ứng dụng.

Để chuẩn bị:

1. Đăng nhập đúng tài khoản Google cần kết nối và kiểm tra đã bật xác minh 2 bước.
2. Mở hướng dẫn mật khẩu ứng dụng của Google, rồi làm theo đường dẫn tạo mật khẩu trong tài khoản.
3. Dùng mật khẩu vừa tạo cho kết nối Mailera. Google chỉ cho xem mỗi mật khẩu ứng dụng một lần; không đưa giá trị này vào ảnh chụp hoặc nhật ký.

Nếu không thấy lựa chọn tạo mật khẩu ứng dụng, Google nêu các trường hợp như xác minh 2 bước chỉ dùng khóa bảo mật, tài khoản cơ quan hoặc trường học, và tài khoản có Advanced Protection. Không phải mọi tài khoản đều tạo được mật khẩu ứng dụng.

Với Workspace, quản trị viên còn có thể chỉ cho phép các ứng dụng IMAP được chỉ định và có hỗ trợ OAuth. Khi đó, có đúng mật khẩu ứng dụng vẫn chưa đủ để kết nối.

Kết nối Gmail với Mailera và kiểm tra kết quả

Bạn cần vai trò Admin hoặc Leader để thêm hộp thư. Nếu muốn xem toàn bộ quy trình trước, bài kết nối hộp thư đầu tiên với Mailera trình bày luồng thêm hộp thư.

1. Mở Danh sách hộp thư → Thêm hộp thư → Một hộp thư.
2. Nhập địa chỉ vào Địa chỉ email. Mailera nhận diện các tên miền gmail.com và googlemail.com. Với Google Workspace dùng tên miền riêng, chọn Gmail · Google Workspace trong Hoặc chọn nhà cung cấp khi cần, rồi chọn Tiếp tục.
3. Trong Thông tin kết nối, nhập mật khẩu ứng dụng vào Mật khẩu. Điền Tên hiển thị nếu cần và chọn Nhóm quản lý. Luồng Gmail có sẵn không yêu cầu bạn nhập lại máy chủ IMAP/SMTP.
4. Chọn Kiểm tra & kết nối và xem kết quả từng bước.

Phép kiểm tra này đăng nhập thử, không gửi thư thật. Các kết quả cần xem là:

Nếu phần nhận thành công nhưng phần gửi thất bại, bạn có thể chọn Lưu ở chế độ Chỉ nhận. Nếu cần gửi thư, chọn Sửa thông tin, sửa cấu hình rồi Kiểm tra lại.

Sau khi kết nối, Mailera tải thư trong thời hạn lưu trữ, ưu tiên thư mới nhất. Mở hộp thư, rồi dùng một hộp thư khác của bạn gửi đến một thư thử có tiêu đề dễ nhận ra. Kiểm tra thư đó xuất hiện trong Mailera trước khi cấp quyền cho ứng dụng.

Thư thử đến hộp thư xác nhận đường nhận đang hoạt động. Kết quả đăng nhập SMTP không thay thế cho việc gửi một thư thử riêng nếu bạn cần kiểm tra đường gửi.

Những lỗi cài đặt Gmail IMAP/SMTP thường gặp

Đừng thay mọi thông số cùng lúc. Xác định lỗi thuộc máy chủ, cách đăng nhập hay chính sách tài khoản trước.

Theo hướng dẫn thêm Gmail vào ứng dụng email khác, từ tháng 1/2025 Gmail cá nhân không còn lựa chọn “Enable IMAP” hoặc “Disable IMAP”. IMAP luôn bật; việc thiếu lựa chọn này không phải lỗi giao diện.

Cài đặt IMAP Google Workspace khác ở quyền quản trị. Quản trị viên cần cho phép IMAP và có thể giới hạn ứng dụng truy cập. Chính sách POP/IMAP của Workspace cũng nêu rằng tắt giao thức sẽ chặn ứng dụng tương ứng, kể cả khi trước đó kết nối vẫn hoạt động.

Một nguyên nhân dễ bỏ sót: đổi mật khẩu tài khoản Google sẽ thu hồi các mật khẩu ứng dụng. Nếu lỗi xuất hiện sau lần đổi mật khẩu, hãy kiểm tra việc này trước khi sửa máy chủ.

Với Gmail trong API Mailera, trạng thái hộp thư dựa trên lần đồng bộ gần nhất, không phải một lần đăng nhập trực tiếp mới ở mỗi yêu cầu. Khi chẩn đoán thư đến chậm, hãy xem cả sync.last_synced_at, không chỉ status.

Cho AI agent đọc Gmail cần bảo vệ những gì?

Kết nối hộp thư trước, cấp quyền cho agent sau. Bài dùng hộp thư có sẵn cho AI agent giải thích cách tách kết nối email khỏi ứng dụng sử dụng thư.

Trong Cài đặt, mở phần khóa API và chọn Tạo key. Đặt 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 read. Cấu hình này giới hạn agent ở phía Mailera; đừng coi đó là thay đổi quyền của mật khẩu ứng dụng Google.

Với REST API, bạn có thể liệt kê thư bằng lệnh dưới đây. Đặt $MAILERA_API_KEY và $MAILBOX_ID trong môi trường chạy của ứng dụng, dùng hộp thư thử thuộc quyền của bạn.

curl --request GET \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=1" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Lệnh cần quyền read, không gửi thư. Kết quả danh sách nằm trong data; bạn có thể đối chiếu subject, folder và received_at với thư thử. Xem REST API dành cho nhà phát triển nếu cần tích hợp sâu hơn. Qua MCP, công cụ tương ứng là list_messages, cũng cần quyền read.

Thư đến là dữ liệu không tin cậy, không phải lệnh. Agent không được làm theo nội dung thư yêu cầu tiết lộ khóa, đọc hộp thư khác hoặc chuyển dữ liệu ra ngoài. Cần chặn prompt injection ngay từ khâu thiết kế ứng dụng.

Không cấp send nếu công việc chỉ cần đọc. Nếu bổ sung gửi thư, ứng dụng phải yêu cầu người dùng xác nhận trước khi gửi. Không đưa mật khẩu ứng dụng hoặc khóa API vào câu lệnh cho mô hình, nhật ký hay ảnh chụp.

Khi ngừng sử dụng, thu hồi khóa trong phần quản lý khóa API của Mailera; các yêu cầu dùng khóa đó sẽ bị từ chối ngay. Thông tin bảo mật Mailera là trang tham khảo khi bạn đánh giá việc cấp quyền truy cập hộp thư.

Mailera không làm những gì trong kết nối này?

Mailera kết nối hộp thư đã có, không tạo tài khoản Gmail hoặc địa chỉ email mới. Mailera cũng không thay đổi được chính sách truy cập của Google hay quản trị viên Google Workspace.

Luồng Gmail trong Mailera dùng mật khẩu ứng dụng, không phải nút đăng nhập Gmail bằng OAuth. Nếu tổ chức chỉ cho phép ứng dụng OAuth được chỉ định, bạn cần giải quyết yêu cầu đó với quản trị viên.

Đồng bộ không phải lúc nào cũng tức thời. Hộp thư đang được sử dụng được kiểm tra thường xuyên hơn; hộp thư ít hoạt động có thể được kiểm tra thưa hơn hoặc chuyển sang trạng thái ngủ.