imaplib --- IMAP4 プロトコルクライアント

ソースコード: Lib/imaplib.py

This module defines three classes, IMAP4, IMAP4_SSL and IMAP4_stream, which encapsulate a connection to an IMAP4 server and implement a large subset of the IMAP4rev1 client protocol as defined in RFC 3501. It is backward compatible with IMAP4 (RFC 1730) servers, but note that the STATUS command is not supported in IMAP4.

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは、WebAssembly プラットフォーム を見てください。

imaplib モジュール内では三つのクラスを提供しており、 IMAP4 は基底クラスとなります:

class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)

このクラスは IMAP4 プロトコルの実際の処理を実装します。 インスタンスの初期化時に接続を作成し、プロトコルのバージョン (IMAP4 または IMAP4rev1) を決定します。 host を指定しない場合は、'' (ローカルホスト) を使います。 port を省略すると、標準の IMAP4 ポート (143) を使います。 オプションの timeout 引数は、接続を試みる際のタイムアウトを秒単位で指定します。 timeout を指定しない場合や None の場合は、ソケットのグローバルなデフォルトのタイムアウトを使います。

IMAP4 クラスは with 文をサポートしています。 このように使うと、with 文を抜けるときに IMAP4 の LOGOUT コマンドが自動的に発行されます。 例えば次のように使います。

>>> from imaplib import IMAP4
>>> with IMAP4("domain.org") as M:
...     M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

バージョン 3.5 で変更: with 構文のサポートが追加されました。

バージョン 3.9 で変更: オプションの timeout 引数が追加されました。

例外は IMAP4 クラスの属性として定義されています:

exception IMAP4.error

何らかのエラー発生の際に送出される例外です。例外の理由は文字列としてコンストラクタに渡されます。

exception IMAP4.abort

IMAP4 サーバのエラーが生じると、この例外が送出されます。この例外は IMAP4.error のサブクラスです。通常、インスタンスを閉じ、新たなインスタンスを再び生成することで、この例外から復旧できます。

exception IMAP4.readonly

この例外は書き込み可能なメールボックスの状態がサーバによって変更された際に送出されます。この例外は IMAP4.error のサブクラスです。他の何らかのクライアントが現在書き込み権限を獲得しており、メールボックスを開きなおして書き込み権限を再獲得する必要があります。

このモジュールではもう一つ、安全 (secure) な接続を使ったサブクラスがあります:

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)

SSL で暗号化されたソケットを介して接続する、IMAP4 のサブクラスです (このクラスを使うには、SSL サポート付きでコンパイルされた socket モジュールが必要です)。 host を指定しない場合は、'' (ローカルホスト) を使います。 port を省略すると、標準の IMAP4-over-SSL ポート (993) を使います。 ssl_context は ssl.SSLContext オブジェクトで、SSL の設定オプション、証明書、秘密鍵を 1 つの構造にまとめられます。 この構造は長期間使い続けることもできます。 推奨される方法については セキュリティで考慮すべき点 を読んでください。

注釈

With the default ssl_context, the connection is encrypted but the server certificate and hostname are not verified. To verify them, pass a context created by ssl.create_default_context().

オプションの timeout 引数は、接続を試みる際のタイムアウトを秒単位で指定します。 timeout を指定しない場合や None の場合は、ソケットのグローバルなデフォルトのタイムアウトを使います。

バージョン 3.3 で変更: ssl_context 引数が追加されました。

バージョン 3.4 で変更: このクラスは ssl.SSLContext.check_hostname によるホスト名の検証と、Server Name Indication に対応しました (ssl.HAS_SNI を参照)。

バージョン 3.9 で変更: オプションの timeout 引数が追加されました。

バージョン 3.12 で変更: 非推奨の keyfile と certfile 引数を削除しました。

さらにもう一つのサブクラスは、子プロセスで確立した接続を使用する場合に使用します:

class imaplib.IMAP4_stream(command)

IMAP4 から派生したサブクラスで、 command を subprocess.Popen() に渡して作成される stdin/stdout ディスクリプタと接続します。

以下のユーティリティ関数が定義されています:

imaplib.Internaldate2tuple(resp)

Parse a bytes-like object containing an IMAP4 INTERNALDATE response and return the corresponding local time. The return value is a time.struct_time tuple or None if the input has wrong format.

imaplib.Int2AP(num)

整数を [A .. P] からなる文字集合を用いて表現した bytes に変換します。

imaplib.ParseFlags(resp)

Converts a bytes-like object containing an IMAP4 FLAGS response to a tuple of individual flags as bytes. The return value is an empty tuple if the input has wrong format.

imaplib.Time2Internaldate(date_time)

date_time を IMAP4 の INTERNALDATE 表現に変換します。 戻り値は "DD-Mmm-YYYY HH:MM:SS +HHMM" 形式の文字列です (ダブルクォートも含みます)。 date_time 引数には、エポックからの秒数を表す数値 (int または float、time.time() の戻り値)、ローカル時刻を表す 9 要素のタプル、time.struct_time のインスタンス (time.localtime() の戻り値)、datetime.datetime の aware なインスタンス、またはダブルクォートで囲んだ文字列を指定できます。 最後の場合、文字列はすでに正しい形式であるとみなされます。

IMAP4 メッセージ番号は、メールボックスに対する変更が行われた後には変化します; 特に、EXPUNGE 命令はメッセージの削除を行いますが、残ったメッセージには再度番号を振りなおします。従って、メッセージ番号ではなく、UID 命令を使い、その UID を利用するよう強く勧めます。

モジュールの末尾に、より拡張的な使用例が収められたテストセクションがあります。

参考

ワシントン大学の IMAP Information Center によるプロトコルの説明文書や、そのプロトコルを実装したサーバのソースは、(ソースコード) https://github.com/uw-imap/imap にあります (メンテナンスされていません)。

IMAP4 オブジェクト

IMAP4rev1 のすべてのコマンドに、大文字または小文字の同名のメソッドが対応しています。

All arguments to commands are converted to strings, except for AUTHENTICATE, and the last argument to APPEND which is passed as an IMAP4 literal. If necessary (the string contains IMAP4 protocol-sensitive characters and isn't enclosed with either parentheses or double quotes) each string is quoted. However, the password argument to the LOGIN command is always quoted. If you want to avoid having an argument string quoted (eg: the flags argument to STORE) then enclose the string in parentheses (eg: r'(\Deleted)'). In general, pass arguments unquoted and let the module quote them as needed. An argument that is already enclosed in double quotes is left unchanged, so that code which quotes arguments itself keeps working.

Each command returns a tuple: (type, [data, ...]) where type is usually 'OK' or 'NO', and data is either the text from the command response, or mandated results from the command. Each data is either a bytes, or a tuple. If a tuple, then the first part is the header of the response, and the second part contains the data (ie: 'literal' value).

以下のコマンドにおける message_set オプションは、操作の対象となるひとつあるいは複数のメッセージを指す文字列です。単一のメッセージ番号 ('1') かメッセージ番号の範囲 ('2:4')、あるいは連続していないメッセージをカンマでつなげたもの ('1:3,6:9') となります。範囲指定でアスタリスクを使用すると、上限を無限とすることができます ('3:*')。

IMAP4 のインスタンスは以下のメソッドを持っています:

IMAP4.append(mailbox, flags, date_time, message)

指定された名前のメールボックスに message を追加します。

flags may be None or a string of IMAP flag tokens. Multiple flags are separated by spaces, for example r'\Seen \Answered'. If flags is not already enclosed in parentheses, parentheses are added automatically.

IMAP4.authenticate(mechanism, authobject)

認証命令です --- 応答の処理が必要です。

mechanism は利用する認証メカニズムを与えます。認証メカニズムはインスタンス変数 capabilities の中に AUTH=mechanism という形式で現れる必要があります。

authobject は呼び出し可能なオブジェクトである必要があります:

data = authobject(response)

サーバからの継続応答を処理するために呼び出され、渡される response 引数は bytes です。 base64 エンコードしてサーバに送信する data を bytes で返す必要があります。 代わりにクライアントの中止応答 * を送信する場合は、None を返してください。

バージョン 3.5 で変更: 文字列のユーザ名とパスワードは ASCII に制限されず、utf-8 にエンコードされるようになりました。

IMAP4.check()

サーバ上のメールボックスにチェックポイントを設定します。

IMAP4.close()

現在選択されているメールボックスを閉じます。削除されたメッセージは書き込み可能メールボックスから除去されます。LOGOUT 前に実行することを勧めます。

IMAP4.copy(message_set, new_mailbox)

message_set で指定したメッセージ群を new_mailbox の末尾にコピーします。

IMAP4.create(mailbox)

mailbox と名づけられた新たなメールボックスを生成します。

IMAP4.delete(mailbox)

mailbox と名づけられた古いメールボックスを削除します。

IMAP4.deleteacl(mailbox, who)

mailbox における who についてのACLを削除(権限を削除)します。

IMAP4.enable(capability)

capability を有効にします (RFC 5161 を参照)。 ほとんどの capability は有効にする必要がありません。 現在サポートされているのは UTF8=ACCEPT capability だけです (RFC 6855 を参照)。

Added in version 3.5: enable() メソッドと RFC 6855 のサポートを追加しました。

IMAP4.expunge()

選択されたメールボックスから削除された要素を永久に除去します。各々の削除されたメッセージに対して、EXPUNGE 応答を生成します。返されるデータには EXPUNGE メッセージ番号を受信した順番に並べたリストが入っています。

IMAP4.fetch(message_set, message_parts)

メッセージ (の一部) を取りよせます。message_parts はメッセージパートの名前を表す文字列を丸括弧で囲ったもので、例えば: "(UID BODY[TEXT])" のようになります。返されるデータはメッセージパートのエンベロープ情報とデータからなるタプルです。

IMAP4.getacl(mailbox)

mailbox に対する ACL を取得します。このメソッドは非標準ですが、Cyrus サーバでサポートされています。

IMAP4.getannotation(mailbox, entry, attribute)

mailbox に対する ANNOTATION を取得します。このメソッドは非標準ですが、Cyrus サーバでサポートされています。

IMAP4.getquota(root)

quota root により、リソース使用状況と制限値を取得します。このメソッドは RFC 2087 で定義されている IMAP4 QUOTA 拡張の一部です。

IMAP4.getquotaroot(mailbox)

指定した mailbox の quota roots のリストを取得します。 このメソッドは rfc2087 で定義されている IMAP4 QUOTA 拡張の一部です。

IMAP4.list(directory='', pattern='*')

pattern にマッチする directory メールボックス名を列挙します。directory の標準の設定値は最上レベルのメールフォルダで、pattern は標準の設定では全てにマッチします。返されるデータには LIST 応答のリストが入っています。

IMAP4.login(user, password)

平文パスワードを使ってクライアントを照合します。password はクオートされます。

IMAP4.login_cram_md5(user, password)

パスワードの保護のため、クライアント認証時に CRAM-MD5 だけを使用します。これは、CAPABILITY レスポンスに AUTH=CRAM-MD5 が含まれる場合のみ有効です。

バージョン 3.13.8 で変更: An IMAP4.error is raised if MD5 support is not available.

IMAP4.logout()

サーバへの接続を遮断します。サーバからの BYE 応答を返します。

バージョン 3.8 で変更: このメソッドは、任意の例外を黙って無視することがなくなりました。

IMAP4.lsub(directory='', pattern='*')

購読しているメールボックス名のうち、ディレクトリ内でパターンにマッチするものを列挙します。directory の標準の設定値は最上レベルのメールフォルダで、pattern は標準の設定では全てにマッチします。返されるデータには返されるデータはメッセージパートエンベロープ情報とデータからなるタプルです。

IMAP4.myrights(mailbox)

mailboxにおける自分のACLを返します (すなわち自分がmailboxで持っている権限を返します)。

IMAP4.namespace()

RFC 2342 で定義されるIMAP名前空間を返します。

IMAP4.noop()

サーバに NOOP を送信します。

IMAP4.open(host, port, timeout=None)

host の port へのソケットを開きます。 オプションの timeout 引数は、接続を試みる際のタイムアウトを秒単位で指定します。 timeout を指定しない場合や None の場合は、ソケットのグローバルなデフォルトのタイムアウトを使います。 また、timeout 引数がゼロの場合は、非ブロッキングソケットの作成を拒否するために ValueError を送出します。 このメソッドは IMAP4 コンストラクタから暗黙的に呼び出されます。 このメソッドで確立した接続オブジェクトは、IMAP4.read()、IMAP4.readline()、IMAP4.send()、IMAP4.shutdown() メソッドで使われます。 このメソッドはオーバーライドできます。

引数 self, host, port を指定して 監査イベント imaplib.open を送出します。

バージョン 3.9 で変更: timeout 引数が追加されました。

IMAP4.partial(message_num, message_part, start, length)

メッセージの一部を取り寄せます。 返されるデータはメッセージパートエンベロープ情報とデータからなるタプルです。

IMAP4.proxyauth(user)

user として認証されたものとします。認証された管理者がユーザの代理としてメールボックスにアクセスする際に使用します。

IMAP4.read(size)

遠隔のサーバから size バイト読み出します。このメソッドはオーバライドすることができます。

IMAP4.readline()

遠隔のサーバから一行読み出します。このメソッドはオーバライドすることができます。

IMAP4.recent()

サーバに更新を促します。新たなメッセージがない場合応答は None になり、そうでない場合 RECENT 応答の値になります。

IMAP4.rename(oldmailbox, newmailbox)

oldmailbox という名前のメールボックスを newmailbox に名称変更します。

IMAP4.response(code)

応答 code を受信していれば、そのデータを返し、そうでなければ None を返します。通常の形式 (usual type) ではなく指定したコードを返します。

IMAP4.search(charset, criterion[, ...])

メールボックスから条件に合うメッセージを検索します。 charset は None でもよく、その場合はサーバへの要求で CHARSET を指定しません。 IMAP プロトコルでは少なくとも 1 つの条件を指定する必要があり、サーバがエラーを返すと例外が送出されます。 enable() コマンドで UTF8=ACCEPT capability を有効にしている場合、charset は None にする必要があります。

以下はプログラム例です:

# M は接続済みの IMAP4 インスタンス...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# または:
typ, msgnums = M.search(None, '(FROM "LDJ")')
IMAP4.select(mailbox='INBOX', readonly=False)

メールボックスを選択します。返されるデータは mailbox 内のメッセージ数 (EXISTS 応答) です。標準の設定では mailbox は 'INBOX' です。readonly が設定された場合、メールボックスに対する変更はできません。

IMAP4.send(data)

遠隔のサーバに data を送信します。このメソッドはオーバライドすることができます。

引数 self, data を指定して 監査イベント imaplib.send を送出します。

IMAP4.setacl(mailbox, who, what)

ACL を mailbox に設定します。このメソッドは非標準ですが、Cyrus サーバでサポートされています。

IMAP4.setannotation(mailbox, entry, attribute[, ...])

ANNOTATION を mailbox に設定します。このメソッドは非標準ですが、Cyrus サーバでサポートされています。

IMAP4.setquota(root, limits)

quota root のリソースの制限値を limits に設定します。 このメソッドは rfc2087 で定義されている IMAP4 QUOTA 拡張の一部です。

IMAP4.shutdown()

open で確立された接続を閉じます。 IMAP4.logout() は暗黙的にこのメソッドを呼び出します。このメソッドはオーバライドすることができます。

IMAP4.socket()

サーバへの接続に使われているソケットインスタンスを返します。

IMAP4.sort(sort_criteria, charset, search_criterion[, ...])

sort 命令は search に結果の並べ替え (sort) 機能をつけた変種です。返されるデータには、条件に合致するメッセージ番号をスペースで分割したリストが入っています。

sort 命令は search_criterion の前に二つの引数を持ちます; sort_criteria のリストを丸括弧で囲ったものと、検索時の charset です。 search と違って、検索時の charset は必須です。 uid sort 命令もあり、search に対する uid search と同じように sort 命令に対応します。 sort 命令はまず、charset 引数の指定に従って 検索条件の文字列を解釈し、メールボックスから与えられた検索条件に合致するメッセージを探します。 次に、合致したメッセージの番号を返します。

IMAP4rev1 拡張命令です。

IMAP4.starttls(ssl_context=None)

STARTTLS コマンドを送信します。 ssl_context 引数は省略可能で、指定する場合は ssl.SSLContext オブジェクトでなければなりません。 これにより IMAP 接続の暗号化が有効になります。 推奨される方法については セキュリティで考慮すべき点 を読んでください。

注釈

With the default ssl_context, the connection is encrypted but the server certificate and hostname are not verified. To verify them, pass a context created by ssl.create_default_context().

Added in version 3.2.

バージョン 3.4 で変更: このメソッドは ssl.SSLContext.check_hostname によるホスト名の検証と、Server Name Indication (ssl.HAS_SNI を参照) をサポートするようになりました。

IMAP4.status(mailbox, names)

mailbox の指定ステータス名の状態情報を要求します。

IMAP4.store(message_set, command, flag_list)

Alters flag dispositions for messages in mailbox. command is specified by section 6.4.6 of RFC 3501 as being one of "FLAGS", "+FLAGS", or "-FLAGS", optionally with a suffix of ".SILENT".

たとえば、すべてのメッセージに削除フラグを設定するには次のようにします:

typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', '\\Deleted')
M.expunge()

注釈

Creating flags containing ']' (for example: "[test]") violates RFC 3501 (the IMAP protocol). However, imaplib has historically allowed creation of such flags, and popular IMAP servers, such as Gmail, accept and produce such flags. There are non-Python programs which also create such flags. Although it is an RFC violation and IMAP clients and servers are supposed to be strict, imaplib still continues to allow such flags to be created for backward compatibility reasons, and as of Python 3.6, handles them if they are sent from the server, since this improves real-world compatibility.

IMAP4.subscribe(mailbox)

新たなメールボックスを購読 (subscribe) します。

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

thread コマンドは search にスレッドの概念を加えた変形版です。返されるデータは空白で区切られたスレッドメンバのリストを含んでいます。

各スレッドメンバは0以上のメッセージ番号からなり、空白で区切られており、親子関係を示しています。

thread コマンドは search_criterion 引数より前に、threading_algorithm と検索用の charset という 2 つの引数を取ります。 search と異なり、検索用の charset 引数は必須です。 uid thread コマンドもあり、uid search が search に対応するのと同様に thread に対応します。 thread コマンドはまず、charset 引数を使って検索条件の文字列を解釈し、指定した条件に合うメッセージをメールボックスから検索します。 次に、指定したスレッド化アルゴリズムに従ってスレッドにまとめたメッセージを返します。

IMAP4rev1 拡張命令です。

IMAP4.uid(command, arg[, ...])

command args を、メッセージ番号ではなく UID で指定されたメッセージ群に対して実行します。命令内容に応じた応答を返します。少なくとも一つの引数を与えなくてはなりません; 何も与えない場合、サーバはエラーを返し、例外が送出されます。

IMAP4.unsubscribe(mailbox)

古いメールボックスの購読を解除 (unsubscribe) します。

IMAP4.unselect()

imaplib.IMAP4.unselect() は、選択されたメールボックスに関連するサーバのリソースを解放し、サーバを認証済みの状態に戻します。 このコマンドは imaplib.IMAP4.close() と同じ処理を行いますが、現在選択されているメールボックスのメッセージを永久に削除することはありません。

Added in version 3.9.

IMAP4.xatom(name[, ...])

サーバから CAPABILITY 応答で通知された単純な拡張命令を許容 (allow) します。

以下の属性が IMAP4 のインスタンス上で定義されています:

IMAP4.capabilities

A tuple of the capabilities advertised by the server, in upper case.

It is set when the connection is established, and refreshed after a successful login(), authenticate() or starttls(), because the server can advertise different capabilities in different connection states.

バージョン 3.13.15 で変更: Refreshed after login() and authenticate().

IMAP4.PROTOCOL_VERSION

サーバから返された CAPABILITY 応答にある、サポートされている最新のプロトコルです。

IMAP4.debug

デバッグ出力を制御するための整数値です。 初期値はモジュール変数 Debug から取られます。 3 より大きい値にすると各命令をトレースします。

IMAP4.utf8_enabled

通常は False の真偽値ですが、UTF8=ACCEPT capability に対する enable() コマンドが成功すると True になります。

Added in version 3.5.

IMAP4 の使用例

メールボックスを開き、すべてのメッセージを取得して表示する最小限の例 (エラーチェックなし) を示します。

import getpass, imaplib

M = imaplib.IMAP4(host='example.org')
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
    typ, data = M.fetch(num, '(RFC822)')
    print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()

注釈

A FETCH response may contain additional or unsolicited data (see RFC 3501, section 7.4.2), so production code should inspect the whole response rather than rely on data[0][1].