Tiện ích IMAP

Tài liệu này mô tả các tiện ích IMAP do Gmail cung cấp và cách nhà phát triển có thể sử dụng các tiện ích đó. Tài liệu này giả định rằng bạn đã nắm rõ giao thức IMAP.

Tổng quan

Gmail cung cấp một tập hợp các tiện ích IMAP để cho phép tác giả của ứng dụng IMAP cung cấp trải nghiệm giống Gmail hơn thông qua IMAP. Thay vào đó, các 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 RESTful.

Bạn có thể sử dụng các tiện ích khi truy cập Gmail thông qua giao thức IMAP tiêu chuẩn hoặc khi kết nối qua OAuth.

Kiểm tra sự hiện diện của các tiện ích

Gmail quảng cáo khả năng hỗ trợ tiện ích trong phản hồi đối với lệnh CAPABILITY. Khả năng hỗ trợ 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 các tính năng được hỗ trợ.

Bạn nên yêu cầu ứng dụng tự thông báo bằng lệnh IMAP ID (RFC 2971) và đưa vào địa chỉ liên hệ làm phương án dự phòng trong trường hợp cần thay đổi các tiện ích này.

Sau đây là ví dụ về quá trình bắt tay và cách 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 LIST 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 phép ứng dụng biết thư mục nào là đặc biệt (ví dụ: \All). Danh sách hiện tại gồm các thư mục đặc biệt: Đánh dấu sao, Quan trọng, Mục đã 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à CAPABILITY mới hoặc thứ gì đó mà ứng dụng cần ENABLEd.

Sau đây là ví dụ về bản ghi cuộc gọi đến 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

Phản hồ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 bị ngừng hoạt động

Lệnh XLIST dành riêng cho Gmail đã bị ngừng hoạt động vào năm 2013 để chuyển sang Tiêu chuẩn danh sách sử dụng đặc biệt của IMAP. Bạn nên yêu cầu ứng dụng di chuyển từ XLIST sang tiêu chuẩn ngành Sử dụng đặc biệt càng sớm càng tốt. Xin lưu ý rằng tên thuộc tính tiêu chuẩn 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ũ.

Tiện ích 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 đủ trong 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ùng một cách như trong giao diện web Gmail.

Sau đây là ví dụ về bản ghi 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 của 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ể xác định một thư duy nhất trên nhiều thư mục. Bạn có thể truy xuất mã nhận dạng thư này thông qua thuộc tính X-GM-MSGID trên lệnh FETCH. Mã nhận dạng thư là một số nguyên không dấu 64 bit và tương đương với số thập phân cho chuỗi thập lục phân của mã nhận dạng được dùng trong giao diện web và API Gmail.

Sau đây là ví dụ về bản ghi cuộc gọi để truy xuất X-GM-MSGID của một thư bằng lệnh FETCH:

a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)

Bạn cũng có thể sử dụng thuộc tính X-GM-MSGID trong lệnh SEARCH hoặc UID SEARCH để tìm số thứ tự hoặc UID của một thư có mã nhận dạng thư của Gmail. Sau đây là ví dụ về bản ghi cuộc gọi để truy xuất UID của một thư bằng lệnh UID SEARCH command:

a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)

Quyền truy cập vào mã nhận dạng chuỗi thư của Gmail: X-GM-THRID

Gmail cung cấp một mã nhận dạng chuỗi thư để liên kết các nhóm thư theo cùng một cách như trong giao diện web Gmail. Bạn có thể truy xuất mã nhận dạng chuỗi thư này thông qua thuộc tính X-GM-THRID trên lệnh FETCH. Mã nhận dạng chuỗi thư là một số nguyên không dấu 64 bit và tương đương với số thập phân cho chuỗi thập lục phân của mã nhận dạng được dùng trong giao diện web và API Gmail.

Sau đây là ví dụ về bản ghi cuộc gọi để truy xuất X-GM-THRID của một số thư (trong hai chuỗi thư) 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ể sử dụng thuộc tính X-GM-THRID trong lệnh SEARCH hoặc UID SEARCH để tìm số thứ tự hoặc UID của các thư trong một chuỗi thư nhất định. Sau đây là ví dụ về bản ghi cuộc gọi để truy xuất UID của một số thư bằng lệnh UID SEARCH:

a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)

Quyền truy cập vào nhãn Gmail: X-GM-LABELS

Gmail coi nhãn là thư mục cho mục đích của IMAP. Do đó, bạn có thể sửa đổi nhãn bằng các lệnh IMAP tiêu chuẩn, CREATE, RENAME và DELETE, hoạt động trên các thư mục. Nhãn hệ thống (là 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. Sử dụng lệnh XLIST để lấy toàn bộ danh sách nhãn cho một hộp thư.

Bạn có thể truy xuất nhãn cho 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 ASTRING được mã hoá ở định dạng UTF-7 nếu thích hợp. Một ASTRING là một nguyên tử hoặc một chuỗi như được xác định bởi RFC.

Sau đây là ví dụ về bản ghi cuộc gọi để truy xuất X-GM-LABELS của một số thư 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ư bằng lệnh STORE kết hợp với thuộc tính X-GM-LABELS. Sau đây là ví dụ về bản ghi cuộc gọi 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ể sử dụng thuộc tính X-GM-LABELS trong lệnh SEARCH hoặc UID SEARCH để tìm số thứ tự hoặc UIDs của tất cả thư trong thư mục có nhãn nhất định. Sau đây là ví dụ về bản ghi cuộc gọi để truy xuất số thứ tự của một số thư 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