ส่วนขยาย 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)

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