เอกสารนี้อธิบายส่วนขยาย 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)
ข้อมูลอ้างอิง
- IMAP: RFC 3501: โปรโตคอลการเข้าถึงข้อความอินเทอร์เน็ต - เวอร์ชัน 4rev1
- รหัส IMAP: RFC 2971: IMAP4 ID EXTENSION
- IMAP สำหรับการใช้งานพิเศษ: RFC 6154: ส่วนขยาย IMAP LIST สำหรับกล่องจดหมายสำหรับการใช้งานพิเศษ