Tài liệu này mô tả các tiện ích IMAP do Gmail cung cấp và cách các nhà phát triển có thể sử dụng các tiện ích này. Tài liệu này giả định rằng bạn đã quen với giao thức IMAP.
Tổng quan
Gmail cung cấp một bộ tiện ích IMAP để cho phép tác giả của các ứng dụng IMAP cung cấp trải nghiệm giống với Gmail hơn thông qua IMAP. Những nhà phát triển tích hợp các tính năng của Gmail vào ứng dụng web hoặc ứng dụng di động có thể muốn sử dụng API Gmail của RESTful.
Bạn có thể sử dụng các tiện ích khi truy cập vào Gmail thông qua giao thức IMAP tiêu chuẩn hoặc khi kết nối qua OAuth.
Đang kiểm tra sự hiện diện của các tiện ích
Gmail quảng cáo tính năng hỗ trợ tiện ích trong phản hồi lệnh CAPABILITY
. Sự hỗ trợ các tiện ích trong tài liệu này được biểu thị bằng sự hiện diện của X-GM-EXT-1
trong danh sách tính năng được hỗ trợ.
Ứng dụng nên tự thông báo bằng lệnh ID IMAP (RFC 2971) và đưa vào địa chỉ liên hệ làm địa chỉ dự phòng trong trường hợp cần phải thay đổi các tiện ích này.
Sau đây là ví dụ về cơ chế bắt tay và sử dụng lệnh CAPABILITY
trên điểm cuối IMAP của Gmail:
* OK Gimap ready for requests from 127.0.0.1 k2if6111336rvb.0
a001 LOGIN username@gmail.com password
a001 OK username@gmail.com authenticated (Success)
a001 OK Login successful
a002 CAPABILITY
* CAPABILITY IMAP4rev1 UNSELECT LITERAL+ IDLE NAMESPACE QUOTA ID XLIST CHILDREN X-GM-EXT-1
a002 OK Success
a003 ID ("name" "clientname" "version" "1.2.3" "vendor" "companyname" "contact" "foo@example.com")
* ID ("name" "GImap" "vendor" "Google, Inc." "support-url" "http://mail.google.com/support" "remote-host" "127.0.0.1")
a003 OK Success
Tiện ích sử dụng đặc biệt của lệnh LIST
Gmail hỗ trợ Tiện ích DANH SÁCH IMAP cho Hộp thư sử dụng đặc biệt, cung cấp các thuộc tính mới cho các thư mục đặc biệt. Các thuộc tính này cho khách hàng biết đó là thư mục đặc biệt (ví dụ: \All
). Danh sách các thư mục đặc biệt hiện tại bao gồm: Thư có gắn dấu sao, Thư quan trọng, Thư đã gửi, Thư nháp, Thư rác, Tất cả thư và Thùng rác. Tất cả phản hồi LIST
đều chứa các thuộc tính Sử dụng đặc biệt này; đây không phải là một CAPABILITY
mới hoặc cần phải là ENABLEd
của ứng dụng.
Dưới đây là bản chép lời mẫu của một cuộc gọi đến số LIST
:
a004 LIST "" "*"
* LIST (\HasNoChildren) "/" "INBOX"
* LIST (\Noselect \HasChildren) "/" "[Gmail]"
* LIST (\HasNoChildren \All) "/" "[Gmail]/All Mail"
* LIST (\HasNoChildren \Drafts) "/" "[Gmail]/Drafts"
* LIST (\HasNoChildren \Important) "/" "[Gmail]/Important"
* LIST (\HasNoChildren \Sent) "/" "[Gmail]/Sent Mail"
* LIST (\HasNoChildren \Junk) "/" "[Gmail]/Spam"
* LIST (\HasNoChildren \Flagged) "/" "[Gmail]/Starred"
* LIST (\HasNoChildren \Trash) "/" "[Gmail]/Trash"
a004 OK Success
Câu trả lời tuân theo tiêu chuẩn Sử dụng đặc biệt với thuộc tính \Important
bổ sung được thêm vào Hộp thư ưu tiên của Gmail (tức là "[Gmail]/Important"
).
XLIST không được dùng nữa
Lệnh XLIST
dành riêng cho Gmail đã không còn được dùng trong năm 2013 và thay vào đó là Tiêu chuẩn danh sách sử dụng đặc biệt IMAP. Khách hàng nên chuyển từ XLIST
sang tiêu chuẩn ngành về Mục đích sử dụng đặc biệt sớm nhất có thể. Xin lưu ý rằng tên của các thuộc tính tiêu chuẩn dành cho Mục đích sử dụng đặc biệt tương tự nhưng không giống với tên thuộc tính XLIST
cũ.
Phần mở rộng của lệnh SEARCH: X-GM-RAW
Để cung cấp quyền truy cập vào cú pháp tìm kiếm đầy đủ của Gmail, Gmail cung cấp thuộc tính tìm kiếm X-GM-RAW
. Các đối số được truyền cùng với thuộc tính X-GM-RAW
khi thực thi lệnh SEARCH
hoặc UID SEARCH
sẽ được diễn giải theo cách tương tự như trong giao diện web của Gmail.
Dưới đây là bản chép lời mẫu của một cuộc gọi đến SEARCH
bằng thuộc tính X-GM-RAW
:
a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)
Quyền truy cập vào mã nhận dạng thư duy nhất trong Gmail: X-GM-MSGID
Gmail cung cấp một mã nhận dạng thư duy nhất cho mỗi email để có thể nhận dạng một thư duy nhất trên nhiều thư mục. Việc truy xuất mã thông báo này được hỗ trợ thông qua thuộc tính X-GM-MSGID
trong lệnh FETCH
. Mã nhận dạng thư là số nguyên 64 bit chưa ký và là số thập phân tương đương với chuỗi mã nhận dạng hex được dùng trong giao diện web và API Gmail.
Dưới đây là ví dụ về bản chép lời của một cuộc gọi để truy xuất X-GM-MSGID
của một tin nhắn bằng lệnh FETCH
:
a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)
Thuộc tính X-GM-MSGID
cũng có thể được dùng trong các lệnh SEARCH
hoặc UID SEARCH
để tìm số thứ tự hoặc UID
của một thư dựa trên mã nhận dạng của thư trong Gmail. Dưới đây là ví dụ về bản chép lời của một cuộc gọi để truy xuất UID
của một tin nhắn bằng lệnh UID SEARCH
:
a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)
Quyền truy cập vào mã chuỗi Gmail: X-GM-THRID
Gmail cung cấp mã nhận dạng chuỗi để liên kết các nhóm thư theo cách tương tự như trong giao diện web của Gmail. Việc truy xuất mã luồng này được hỗ trợ thông qua thuộc tính X-GM-THRID
trong lệnh FETCH
. Mã nhận dạng luồng là một số nguyên 64 bit chưa ký và là số thập phân tương đương với chuỗi mã nhận dạng hex được sử dụng trong giao diện web và API Gmail.
Sau đây là bản chép lời mẫu của một lệnh gọi để truy xuất X-GM-THRID
của một số tin nhắn (trong 2 chuỗi) bằng lệnh FETCH
:
a008 FETCH 1:4 (X-GM-THRID)
* 1 FETCH (X-GM-THRID 1278455344230334865)
* 2 FETCH (X-GM-THRID 1266894439832287888)
* 3 FETCH (X-GM-THRID 1266894439832287888)
* 4 FETCH (X-GM-THRID 1266894439832287888)
a008 OK FETCH (Success)
Bạn cũng có thể dùng thuộc tính X-GM-THRID
trong các lệnh SEARCH
hoặc UID SEARCH
để tìm số thứ tự hoặc UID
của các thông báo trong một luồng nhất định. Dưới đây là ví dụ về bản chép lời của một cuộc gọi để truy xuất UID
của một số tin nhắn bằng lệnh UID SEARCH
:
a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)
Truy cập vào nhãn Gmail: X-GM-LABEL
Gmail coi nhãn là thư mục vì mục đích IMAP. Do đó, bạn có thể sửa đổi nhãn bằng cách sử dụng lệnh IMAP tiêu chuẩn, CREATE
, RENAME
và DELETE
, thao tác trên các thư mục. Nhãn hệ thống là các nhãn do Gmail tạo, được dành riêng và có tiền tố "[Gmail]" hoặc "[GoogleMail]" trong danh sách nhãn. Dùng lệnh XLIST
để lấy toàn bộ danh sách nhãn của một hộp thư.
Bạn có thể truy xuất các nhãn của một thư nhất định bằng cách sử dụng thuộc tính X-GM-LABELS
với lệnh FETCH
. Thuộc tính này được trả về dưới dạng danh sách các ASTRING
, được mã hoá bằng UTF-7 khi thích hợp. ASTRING
là một atom hoặc một chuỗi do RFC xác định.
Dưới đây là ví dụ về bản chép lời của một cuộc gọi để truy xuất X-GM-LABELS
của một số tin nhắn bằng lệnh FETCH
:
a010 FETCH 1:4 (X-GM-LABELS)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante"))
* 2 FETCH (X-GM-LABELS (foo))
* 3 FETCH (X-GM-LABELS ())
* 4 FETCH (X-GM-LABELS (\Drafts))
a010 OK FETCH (Success)
Bạn có thể thêm nhãn vào một thông báo bằng lệnh STORE
kết hợp với thuộc tính X-GM-LABELS
. Sau đây là bản chép lời mẫu minh hoạ việc thêm nhãn vào một thư:
a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)
Bạn cũng có thể dùng thuộc tính X-GM-LABELS
trong các lệnh SEARCH
hoặc UID SEARCH
để tìm số thứ tự hoặc UID
của tất cả thư trong thư mục có một nhãn cho trước. Dưới đây là ví dụ về bản chép lời của một cuộc gọi để truy xuất số thứ tự của một số tin nhắn bằng lệnh SEARCH
:
a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)
Tài liệu tham khảo
- IMAP: RFC 3501: TÀI LIỆU TRUY CẬP THÔNG TIN InterNET - PHIÊN BẢN 4rev1
- Mã IMAP: RFC 2971: PHẦN MỞ RỘNG Mã IMAP4
- Sử dụng đặc biệt IMAP: RFC 6154: Tiện ích DANH SÁCH IMAP cho Hộp thư sử dụng đặc biệt