ส่วนขยาย 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 สำหรับกล่องจดหมายที่มีการใช้งานพิเศษ ซึ่งระบุแอตทริบิวต์ใหม่สำหรับโฟลเดอร์พิเศษ แอตทริบิวต์เหล่านี้ช่วยให้ไคลเอ็นต์ทราบว่าโฟลเดอร์ใดเป็นโฟลเดอร์พิเศษ (เช่น \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]/Important") ของ Gmail

เราเลิกใช้งาน 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 บิต และเป็นทศนิยมที่เทียบเท่าสตริงฐาน 16 ของรหัสที่ใช้ในเว็บอินเทอร์เฟซและ 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 บิต และเป็นทศนิยมที่เทียบเท่าสตริงฐาน 16 ของรหัสที่ใช้ในเว็บอินเทอร์เฟซและ 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)

ข้อมูลอ้างอิง