ส่วนขยาย IMAP

เอกสารนี้อธิบายส่วนขยาย IMAP ที่ Gmail มีให้และวิธีที่นักพัฒนาแอปอาจใช้ส่วนขยายดังกล่าว เอกสารนี้ถือว่าคุณคุ้นเคยกับโปรโตคอล IMAP เป็นอย่างดี

ภาพรวม

Gmail มีชุดส่วนขยาย IMAP เพื่อให้ผู้สร้างไคลเอ็นต์ IMAP มอบประสบการณ์การใช้งานที่คล้ายกับ Gmail มากขึ้นผ่าน IMAP นักพัฒนาซอฟต์แวร์ที่ผสานรวมฟีเจอร์ Gmail เข้ากับเว็บหรือแอปบนอุปกรณ์เคลื่อนที่อาจต้องการใช้ Gmail API แบบ RESTful แทน

ส่วนขยายอาจใช้ได้เมื่อเข้าถึง Gmail ผ่านโปรโตคอล IMAP มาตรฐานหรือเมื่อเชื่อมต่อผ่าน OAuth

การตรวจสอบว่ามีส่วนขยาย

Gmail จะโฆษณาการรองรับส่วนขยายในการตอบกลับคำสั่ง CAPABILITY การรองรับส่วนขยายในเอกสารนี้จะระบุด้วยเครื่องหมาย X-GM-EXT-1 ในรายการความสามารถที่รองรับ

เราขอแนะนำให้ไคลเอ็นต์ประกาศตัวเองด้วยคำสั่ง IMAP ID (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 รองรับส่วนขยาย LIST ของ 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 (เช่น "[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 บิต และเป็นค่าทศนิยมที่เทียบเท่ากับสตริงเลขฐาน 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 หรือ string ตามที่กำหนดโดย 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)

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