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 レスポンスにはこれらの Special-Use 属性が含まれています。これは新しい 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

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

XLIST は非推奨

Gmail 固有の XLIST コマンドは、IMAP Special-Use List Standard の導入に伴い、2013 年に非推奨となりました。クライアントは、できるだけ早く 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)

X-GM-MSGID 属性は、SEARCH コマンドまたは UID SEARCH コマンドで、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)

X-GM-THRID 属性は、SEARCH コマンドまたは UID SEARCH コマンドで、指定されたスレッド内のメッセージのシーケンス番号または 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]」という接頭辞が付いています。XLIST コマンドを使用して、メールボックスのラベルのリスト全体を取得します。

特定のメッセージのラベルを取得するには、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)

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

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

参照