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 ではなく、クライアントが 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 の優先受信トレイ（"[Gmail]/Important"）用に \Important 属性が追加されています。

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

Gmail 固有の XLIST コマンドは、2013 年に非推奨となり、IMAP 特別用途リスト標準に置き換えられました。XLIST から特別用途の業界標準にできるだけ早く移行することを強くおすすめします。特別な用途の標準属性名は、以前の 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 で定義されているアトムまたは文字列です。

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

参照