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 エンドポイントでの handshake と 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 拡張機能をサポートしています。これにより、特別なフォルダに新しい属性が提供されます。これらの属性により、どのフォルダが特別なフォルダ（例:\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

レスポンスは特殊用途標準に従っており、Gmail の優先トレイ用に \Important 属性が追加されています（"[Gmail]/Important" など）。

XLIST のサポートが終了しました

Gmail 固有の XLIST コマンドは 2013 年にサポートを終了し、IMAP Special-Use List Standard に置き換えられました。クライアント様には、できるだけ早く XLIST から特別用途の業界標準に移行することを強くおすすめします。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または文字列です。

以下は、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)

ラベルをメッセージに追加するには、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)

参照