IMAP 拡張機能

このドキュメントでは、Gmail が提供する IMAP 拡張機能と、デベロッパーがそれらを使用する方法について説明します。このドキュメントは、IMAP プロトコルに精通していることを前提としています。

概要

Gmail は、IMAP クライアントの作成者が IMAP を通じて Gmail に近いエクスペリエンスを提供できるように、一連の IMAP 拡張機能を提供しています。Gmail の機能をウェブアプリやモバイルアプリに統合するデベロッパーは、RESTful な Gmail API の使用を検討してください。

拡張機能は、標準の IMAP プロトコルを使用して Gmail にアクセスする場合や、OAuth で接続する場合に使用できます。

拡張機能の有無を確認する

Gmail は、CAPABILITY コマンドへのレスポンスで拡張機能のサポートをアドバタイズします。サポートされている機能のリストに X-GM-EXT-1 が含まれている場合は、このドキュメントで説明する拡張機能がサポートされていることを示します。

クライアントは IMAP ID コマンド（RFC 2971）を使用して自己をアナウンスし、これらの拡張機能の変更が必要になった場合に備えて、連絡先アドレスをフォールバックとして含めることを強くおすすめします。

Gmail IMAP エンドポイントでの CAPABILITY コマンドのハンドシェイクと使用例を次に示します。

* 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 LIST Extension for Special-Use Mailboxes をサポートしています。これらの属性により、クライアントは \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

このレスポンスは、Gmail の優先トレイ用に \Important 属性（つまり "[Gmail]/Important"）が追加された Special-Use 標準に準拠しています。

XLIST は非推奨

Gmail 固有の XLIST コマンドは、2013 年に IMAP Special-Use List Standard に置き換えられました。XLIST から Special-Use 業界標準への移行をできるだけ早く行うことを強くおすすめします。Special-Use 標準属性名は、以前の XLIST 属性名と似ていますが、同じではありません。

SEARCH コマンドの拡張機能: X-GM-RAW

Gmail の検索構文全体にアクセスできるように、Gmail は X-GM-RAW 検索属性を提供します。SEARCH コマンドまたは UID SEARCH コマンドを実行するときに X-GM-RAW 属性で渡される引数は、Gmail ウェブ インターフェースと同じように解釈されます。

以下は、X-GM-RAW 属性を使用して SEARCH を呼び出した場合の文字起こしの例です。

a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)

Gmail の一意のメッセージ ID（X-GM-MSGID）へのアクセス

Gmail では、複数のフォルダにわたって一意のメッセージを識別できるように、各メールに一意のメッセージ ID が付与されます。このメッセージ ID は、FETCH コマンドの X-GM-MSGID 属性を使用して取得できます。メッセージ ID は 64 ビットの符号なし整数で、ウェブ インターフェースと Gmail API で使用される ID の 16 進数文字列の 10 進数に相当します。

次の例は、FETCH コマンドを使用してメッセージの X-GM-MSGID を取得する呼び出しの文字起こしです。

a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)

SEARCH コマンドまたは UID SEARCH コマンドで X-GM-MSGID 属性を使用して、Gmail のメッセージ ID が指定されたメッセージのシーケンス番号または UID を見つけることもできます。次の例は、UID SEARCH コマンドを使用してメッセージの UID を取得する呼び出しの文字起こしです。

a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)

Gmail スレッド ID へのアクセス: X-GM-THRID

Gmail では、Gmail ウェブ インターフェースと同じように、メッセージのグループを関連付けるためのスレッド ID が提供されます。このスレッド ID は、FETCH コマンドの X-GM-THRID 属性を使用して取得できます。スレッド ID は 64 ビットの符号なし整数で、ウェブ インターフェースと Gmail API で使用される ID の 16 進数文字列の 10 進数表現です。

次の例は、FETCH コマンドを使用して（2 つのスレッド内の）複数のメッセージの X-GM-THRID を取得する呼び出しの文字起こしです。

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)

SEARCH コマンドまたは UID SEARCH コマンドで X-GM-THRID 属性を使用して、指定されたスレッド内のメッセージのシーケンス番号または UID を見つけることもできます。次の例は、UID SEARCH コマンドを使用して複数のメッセージの UID を取得する呼び出しの文字起こしです。

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 コマンドを使用します。

特定のメッセージのラベルを取得するには、FETCH コマンドで X-GM-LABELS 属性を使用します。属性は、必要に応じて UTF-7 でエンコードされた ASTRING のリストとして返されます。ASTRING は、RFC で定義されている atom または string です。

次の例は、FETCH コマンドを使用して複数のメッセージの X-GM-LABELS を取得する呼び出しの文字起こしです。

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)

X-GM-LABELS 属性と組み合わせて STORE コマンドを使用すると、メッセージにラベルを追加できます。メッセージにラベルを追加する方法を示す文字起こしの例を次に示します。

a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)

SEARCH コマンドまたは UID SEARCH コマンドで X-GM-LABELS 属性を使用して、指定したラベルが付いたフォルダ内のすべてのメッセージのシーケンス番号または UID を見つけることもできます。次の例は、SEARCH コマンドを使用して複数のメッセージのシーケンス番号を取得する呼び出しのトランスクリプトの例です。

a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)

参照