ส่วนขยาย IMAP

เอกสารนี้อธิบายส่วนขยาย 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)

รายการอ้างอิง