เอกสารนี้อธิบายส่วนขยาย IMAP ที่ Gmail มีให้และวิธีที่นักพัฒนาซอฟต์แวร์ใช้งาน เอกสารนี้จะถือว่าคุ้นเคยกับโปรโตคอล IMAP
ภาพรวม
Gmail มีชุดส่วนขยาย IMAP ที่ช่วยให้ผู้เขียนไคลเอ็นต์ IMAP มอบประสบการณ์การใช้งานที่คล้ายคลึงกับ Gmail มากขึ้นผ่าน IMAP นักพัฒนาซอฟต์แวร์ที่ผสานรวมฟีเจอร์ของ Gmail เข้ากับเว็บหรือแอปบนอุปกรณ์เคลื่อนที่อาจต้องการใช้ Gmail API ของ RESTful แทน
ระบบอาจใช้ส่วนขยายนี้เมื่อเข้าถึง Gmail ผ่านโปรโตคอล IMAP มาตรฐานหรือเมื่อเชื่อมต่อผ่าน OAuth
กำลังตรวจหาส่วนขยาย
Gmail โฆษณาการรองรับส่วนขยายเพื่อตอบสนองต่อคำสั่ง CAPABILITY
การรองรับส่วนขยายในเอกสารนี้จะระบุด้วย X-GM-EXT-1
ในรายการความสามารถที่รองรับ
ขอแนะนำให้ไคลเอ็นต์ประกาศตัวเองโดยใช้คำสั่งรหัส IMAP (RFC 2971) และใส่ที่อยู่ติดต่อสำรองไว้ในกรณีที่ต้องมีการเปลี่ยนแปลงส่วนขยายเหล่านี้
ตัวอย่างแฮนด์เชคและการใช้คำสั่ง CAPABILITY
ในปลายทาง IMAP ของ 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
ส่วนขยายสำหรับการใช้แบบพิเศษของคำสั่ง LIST
Gmail รองรับส่วนขยาย IMAP LIST สำหรับกล่องจดหมายที่ใช้งานพิเศษ ซึ่งมีแอตทริบิวต์ใหม่สำหรับโฟลเดอร์พิเศษ แอตทริบิวต์เหล่านี้ช่วยให้ไคลเอ็นต์ทราบว่าโฟลเดอร์ใดเป็นโฟลเดอร์พิเศษ (เช่น \All
) รายการโฟลเดอร์พิเศษในปัจจุบันประกอบด้วยรายการที่ติดดาว สำคัญ รายการที่ส่งแล้ว ร่างจดหมาย จดหมายขยะ อีเมลทั้งหมด และถังขยะ คำตอบทั้งหมด LIST
รายการมีแอตทริบิวต์ "การใช้งานพิเศษ" เหล่านี้ ไม่ใช่ CAPABILITY
ใหม่หรือสิ่งที่ไคลเอ็นต์จำเป็นต้องเป็น ENABLEd
ต่อไปนี้เป็นตัวอย่างข้อความถอดเสียงของการโทรหา 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
การตอบกลับเป็นไปตามมาตรฐาน "การใช้งานพิเศษ" ที่มีแอตทริบิวต์ \Important
เพิ่มเติมเพิ่มเข้ามาสำหรับกล่องจดหมายสำคัญของ Gmail (นั่นคือ "[Gmail]/Important"
)
XLIST เลิกใช้งานแล้ว
คำสั่ง XLIST
สำหรับ Gmail โดยเฉพาะถูกเลิกใช้งานในปี 2013 เพื่อใช้มาตรฐานรายการการใช้งานแบบพิเศษของ IMAP เราขอแนะนำอย่างยิ่งให้ลูกค้าย้ายข้อมูลจาก XLIST
ไปยังมาตรฐานอุตสาหกรรม "การใช้งานพิเศษ" โดยเร็วที่สุด โปรดทราบว่าชื่อแอตทริบิวต์มาตรฐาน "ใช้แบบพิเศษ" คล้ายกับชื่อแอตทริบิวต์ XLIST
เดิม
ส่วนขยายของคำสั่ง SEARCH: X-GM-RAW
Gmail มีแอตทริบิวต์การค้นหา X-GM-RAW
เพื่อให้สิทธิ์เข้าถึงไวยากรณ์การค้นหาของ Gmail อย่างเต็มรูปแบบ อาร์กิวเมนต์ที่ส่งผ่านพร้อมกับแอตทริบิวต์ X-GM-RAW
เมื่อเรียกใช้คำสั่ง SEARCH
หรือ UID SEARCH
จะได้รับการตีความในลักษณะเดียวกับในอินเทอร์เฟซทางเว็บของ Gmail
ต่อไปนี้เป็นตัวอย่างข้อความถอดเสียงการโทรไปหา SEARCH
โดยใช้แอตทริบิวต์ X-GM-RAW
a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)
สิทธิ์เข้าถึงรหัสข้อความที่ไม่ซ้ำกันของ Gmail: X-GM-MSGID
Gmail จะกำหนดรหัสข้อความที่ไม่ซ้ำกันให้อีเมลแต่ละฉบับ เพื่อให้สามารถระบุข้อความที่ไม่ซ้ำกันในหลายโฟลเดอร์ได้ ระบบรองรับการเรียกรหัสข้อความนี้ผ่านทางแอตทริบิวต์ X-GM-MSGID
ในคำสั่ง FETCH
รหัสข้อความคือจำนวนเต็มที่ไม่มีเครื่องหมาย 64 บิต และมีค่าเทียบเท่ากับสตริงฐานสิบหกของรหัสที่ใช้ในอินเทอร์เฟซของเว็บและ Gmail API
ต่อไปนี้เป็นตัวอย่างข้อความถอดเสียงของการโทรเพื่อเรียก X-GM-MSGID
ของข้อความที่มีคำสั่ง FETCH
a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)
นอกจากนี้ แอตทริบิวต์ X-GM-MSGID
ยังใช้ในคำสั่ง SEARCH
หรือ UID SEARCH
เพื่อค้นหาหมายเลขลำดับหรือ UID
ของข้อความที่ระบุรหัสข้อความของ Gmail ได้ด้วย ต่อไปนี้เป็นตัวอย่างข้อความถอดเสียงของการโทรเพื่อเรียก UID
ของข้อความโดยใช้คำสั่ง UID SEARCH
a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)
สิทธิ์เข้าถึงรหัสชุดข้อความของ Gmail: X-GM-THRID
Gmail จะกำหนดรหัสชุดข้อความให้เพื่อเชื่อมโยงกลุ่มข้อความในลักษณะเดียวกับในอินเทอร์เฟซทางเว็บของ Gmail ระบบรองรับการดึงข้อมูลรหัสชุดข้อความนี้ผ่านแอตทริบิวต์ X-GM-THRID
ในคำสั่ง FETCH
รหัสชุดข้อความจะเป็นจำนวนเต็มที่ไม่มีเครื่องหมาย 64 บิต และมีค่าเทียบเท่ากับสตริงฐานสิบหกของรหัสที่ใช้ในเว็บอินเทอร์เฟซและ Gmail API
ต่อไปนี้เป็นตัวอย่างข้อความถอดเสียงของการโทรเพื่อเรียก X-GM-THRID
ของข้อความหลายรายการ (ใน 2 ชุดข้อความ) ด้วยคำสั่ง 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)
นอกจากนี้ แอตทริบิวต์ X-GM-THRID
ยังใช้ในคำสั่ง SEARCH
หรือ UID SEARCH
เพื่อค้นหาหมายเลขลำดับหรือ UID
ของข้อความในชุดข้อความได้ ต่อไปนี้เป็นตัวอย่างข้อความถอดเสียงของการโทรเพื่อเรียก UID
ของข้อความหลายรายการโดยใช้คำสั่ง UID SEARCH
a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)
การเข้าถึงป้ายกำกับ Gmail: X-GM-LABELS
Gmail ถือว่าป้ายกำกับเป็นโฟลเดอร์เพื่อวัตถุประสงค์ของ IMAP ด้วยเหตุนี้ ป้ายกำกับจึงแก้ไขได้โดยใช้คำสั่ง IMAP มาตรฐาน CREATE
, RENAME
และ DELETE
ที่ดำเนินการกับโฟลเดอร์ ป้ายกำกับของระบบ ซึ่งเป็นป้ายกำกับที่สร้างโดย Gmail จะมีคำว่า "[Gmail]" หรือ "[GoogleMail]" นำหน้าในรายการป้ายกำกับนั้น ใช้คำสั่ง XLIST
เพื่อรับรายการป้ายกำกับทั้งหมดสำหรับกล่องจดหมาย
คุณเรียกดูป้ายกำกับของข้อความหนึ่งๆ ได้โดยใช้แอตทริบิวต์ X-GM-LABELS
ด้วยคำสั่ง FETCH
แอตทริบิวต์นี้แสดงผลเป็นรายการ ASTRING
โดยเข้ารหัส UTF-7 ตามความเหมาะสม ASTRING
คือ atom หรือสตริงตามที่กำหนดโดย RFC
ต่อไปนี้เป็นตัวอย่างข้อความถอดเสียงของการโทรเพื่อเรียก X-GM-LABELS
ของข้อความจำนวนมากที่มีคำสั่ง 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)
คุณเพิ่มป้ายกำกับในข้อความได้ด้วยคำสั่ง STORE
ร่วมกับแอตทริบิวต์ X-GM-LABELS
ต่อไปนี้เป็นตัวอย่างข้อความถอดเสียงที่แสดงการเพิ่มป้ายกำกับในข้อความ
a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)
นอกจากนี้ แอตทริบิวต์ X-GM-LABELS
ยังใช้ในคำสั่ง SEARCH
หรือ UID SEARCH
เพื่อค้นหาหมายเลขลำดับหรือ UID
ของข้อความทั้งหมดในโฟลเดอร์ที่มีป้ายกำกับที่ระบุได้ด้วย ต่อไปนี้เป็นตัวอย่างข้อความถอดเสียงของการเรียกใช้เพื่อเรียกหมายเลขลำดับของข้อความหลายรายการโดยใช้คำสั่ง SEARCH
a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)
รายการอ้างอิง
- IMAP: RFC 3501: โปรโตคอลการเข้าถึงข้อความทางอินเทอร์เน็ต - เวอร์ชัน 4rev1
- รหัส IMAP: RFC 2971: ส่วนขยายรหัส IMAP4
- การใช้งานแบบพิเศษของ IMAP: RFC 6154: ส่วนขยาย IMAP LIST สำหรับกล่องจดหมายที่ใช้งานพิเศษ