ส่วนขยาย 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 ใหม่หรือสิ่งที่ไคลเอ็นต์ต้องเปิดใช้

ต่อไปนี้เป็นตัวอย่างการถอดเสียงการโทรไปยัง 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]" ในรายการป้ายกำกับ ใช้คำสั่ง LIST เพื่อดูรายการป้ายกำกับทั้งหมด ของกล่องจดหมาย

คุณสามารถดึงป้ายกำกับสำหรับข้อความที่ต้องการได้โดยใช้X-GM-LABELS แอตทริบิวต์กับคำสั่ง FETCH ระบบจะแสดงแอตทริบิวต์เป็นรายการของ ASTRING ที่เข้ารหัสใน UTF-7 ตามความเหมาะสม ASTRING คือ อะตอมหรือ สตริงตามที่กำหนด โดย 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)

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