imaplib — IMAP4プロトコルクライアント—Pythonドキュメント

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

ソースコード： ：source： `Lib / imaplib.py`

---

このモジュールは、 IMAP4 、 IMAP4_SSL 、 IMAP4_stream の3つのクラスを定義します。これらのクラスは、IMAP4サーバーへの接続をカプセル化し、定義されたIMAP4rev1クライアントプロトコルの大規模なサブセットを実装します。 RFC 2060 内。 IMAP4（ RFC 1730 ）サーバーとの下位互換性がありますが、STATUSコマンドはIMAP4ではサポートされていないことに注意してください。

imaplib モジュールによって3つのクラスが提供されます。 IMAP4 は基本クラスです。

class imaplib.IMAP4(host=, port=IMAP4_PORT)

このクラスは、実際のIMAP4プロトコルを実装します。 インスタンスが初期化されると、接続が作成され、プロトコルバージョン（IMAP4またはIMAP4rev1）が決定されます。 host が指定されていない場合は、（ローカルホスト）が使用されます。 ポートを省略すると、標準のIMAP4ポート（143）が使用されます。

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 ステートメントのサポートが追加されました。

IMAP4 クラスの属性として、次の3つの例外が定義されています。

exception IMAP4.error

エラーが発生すると例外が発生します。 例外の理由は、ストリングとしてコンストラクターに渡されます。

exception IMAP4.abort

IMAP4サーバーエラーにより、この例外が発生します。 これは IMAP4.error のサブクラスです。 インスタンスを閉じて新しいインスタンスをインスタンス化すると、通常、この例外からの回復が可能になることに注意してください。

exception IMAP4.readonly

この例外は、書き込み可能なメールボックスのステータスがサーバーによって変更された場合に発生します。 これは IMAP4.error のサブクラスです。 他のクライアントが書き込み権限を持っているため、書き込み権限を再度取得するには、メールボックスを再度開く必要があります。

安全な接続のためのサブクラスもあります：

class imaplib.IMAP4_SSL(host=, port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None)

これは、SSL暗号化ソケットを介して接続する IMAP4 から派生したサブクラスです（このクラスを使用するには、SSLサポートでコンパイルされたソケットモジュールが必要です）。 host が指定されていない場合は、（ローカルホスト）が使用されます。 ポートを省略すると、標準のIMAP4-over-SSLポート（993）が使用されます。 ssl_context は ssl.SSLContext オブジェクトであり、SSL構成オプション、証明書、および秘密鍵を単一の（潜在的に長寿命の）構造にバンドルできます。 ベストプラクティスについては、セキュリティに関する考慮事項をお読みください。

keyfile および certfile は、 ssl_context のレガシー代替手段であり、SSL接続用のPEM形式の秘密鍵および証明書チェーンファイルを指すことができます。 keyfile / certfile パラメーターは ssl_context と相互に排他的であり、 keyfile /の場合に ValueError が発生することに注意してください。 certfile は、 ssl_context とともに提供されます。

バージョン3.3で変更： ssl_context パラメーターが追加されました。

バージョン3.4で変更：クラスは ssl.SSLContext.check_hostname および Server Name Indication によるホスト名チェックをサポートするようになりました（ ssl.HAS_SNI を参照） ）。

バージョン3.6以降非推奨： keyfile および certfile は非推奨になり、 ssl_context が優先されます。 代わりに ssl.SSLContext.load_cert_chain（）を使用するか、 ssl.create_default_context（）にシステムの信頼できるCA証明書を選択させてください。

2番目のサブクラスは、子プロセスによって作成された接続を許可します。

class imaplib.IMAP4_stream(command)

これは、コマンドをsubprocess.Popen()に渡すことによって作成されたstdin/stdoutファイル記述子に接続する IMAP4 から派生したサブクラスです。

次のユーティリティ関数が定義されています。

imaplib.Internaldate2tuple(datestr)

IMAP4 INTERNALDATE文字列を解析し、対応する現地時間を返します。 戻り値は、 time.struct_time タプル、または文字列の形式が間違っている場合はNoneです。

imaplib.Int2AP(num)

セット[A ..の文字を使用して、整数をバイト表現に変換します。 P]。

imaplib.ParseFlags(flagstr)

IMAP4 FLAGS応答を個々のフラグのタプルに変換します。

imaplib.Time2Internaldate(date_time)

date_time をIMAP4 INTERNALDATE表現に変換します。 戻り値は、"DD-Mmm-YYYY HH:MM:SS +HHMM"（二重引用符を含む）の形式の文字列です。 date_time 引数は、エポックからの秒数（ time.time（）によって返される）を表す数値（intまたはfloat）、 time.time（）によって返される）、[ X184X] time.struct_time （ time.localtime（）によって返される）、 datetime.datetime の認識インスタンス、または二重引用符で囲まれた文字列。 最後のケースでは、すでに正しい形式になっていると見なされます。

メールボックスが変更されると、IMAP4メッセージ番号が変更されることに注意してください。 特に、EXPUNGEコマンドが削除を実行した後、残りのメッセージの番号が付け直されます。 したがって、UIDコマンドで代わりにUIDを使用することを強くお勧めします。

モジュールの最後には、より広範な使用例を含むテストセクションがあります。

も参照してください

ワシントン大学のIMAPインフォメーションセンターによるプロトコルとそれを実装するサーバーのソースを説明するドキュメントはすべて、（ソースコード） https://github.com/uw-imap/imapにあります。 （メンテナンスされていません）。

IMAP4オブジェクト

すべてのIMAP4rev1コマンドは、大文字または小文字の同じ名前のメソッドで表されます。

コマンドへのすべての引数は、AUTHENTICATEと、IMAP4リテラルとして渡されるAPPENDへの最後の引数を除いて、文字列に変換されます。 必要に応じて（文字列にはIMAP4プロトコルに依存する文字が含まれ、括弧または二重引用符で囲まれていません）、各文字列は引用符で囲まれます。 ただし、LOGINコマンドの password 引数は常に引用符で囲まれています。 引数文字列が引用されるのを避けたい場合（例： flags 引数からSTORE）、文字列を括弧で囲みます（例：r'(\Deleted)'）。

各コマンドはタプルを返します：(type, [data, ...])ここで、 type は通常'OK'または'NO'であり、 data はコマンド応答、またはコマンドからの必須の結果。 各データは、bytesまたはタプルのいずれかです。 タプルの場合、最初の部分は応答のヘッダーであり、2番目の部分にはデータ（つまり、「リテラル」値）が含まれます。

以下のコマンドの message_set オプションは、処理対象の1つ以上のメッセージを指定する文字列です。 単純なメッセージ番号（'1'）、メッセージ番号の範囲（'2:4'）、またはコンマで区切られた連続しない範囲のグループ（'1:3,6:9'）の場合があります。 範囲には、無限の上限（'3:*'）を示すアスタリスクを含めることができます。

IMAP4 インスタンスには次のメソッドがあります。

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

名前付きメールボックスにメッセージを追加します。

IMAP4.authenticate(mechanism, authobject)

Authenticateコマンド—応答処理が必要です。

メカニズムは、使用する認証メカニズムを指定します。これは、インスタンス変数capabilitiesにAUTH=mechanismの形式で表示されます。

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

data = authobject(response)

サーバー継続応答を処理するために呼び出されます。 渡される response 引数は、bytesになります。 base64でエンコードされてサーバーに送信されるbytes data を返す必要があります。 代わりにクライアントアボート応答*を送信する必要がある場合は、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)

メールボックスのwhoに設定されているACLを削除します（権限を削除します）。

IMAP4.enable(capability)

機能を有効にします（ RFC 5161 を参照）。 ほとんどの機能を有効にする必要はありません。 現在、UTF8=ACCEPT機能のみがサポートされています（ RFC 6855 を参照）。

バージョン3.5の新機能： enable（）メソッド自体、および RFC 6855 のサポート。

IMAP4.expunge()

選択したメールボックスから削除されたアイテムを完全に削除します。 削除されたメッセージごとにEXPUNGE応答を生成します。 返されるデータには、EXPUNGEメッセージ番号のリストが受信順に含まれています。

IMAP4.fetch(message_set, message_parts)

メッセージ（の一部）をフェッチします。 message_parts は、括弧で囲まれたメッセージパーツ名の文字列である必要があります（例："(UID BODY[TEXT])"）。 返されるデータは、メッセージ部分のエンベロープとデータのタプルです。

IMAP4.getacl(mailbox)

メールボックスのACLを入手してください。 この方法は非標準ですが、Cyrusサーバーでサポートされています。

IMAP4.getannotation(mailbox, entry, attribute)

メールボックスに指定されたANNOTATIONを取得します。 この方法は非標準ですが、Cyrusサーバーでサポートされています。

IMAP4.getquota(root)

quota root のリソース使用量と制限を取得します。 このメソッドは、rfc2087で定義されているIMAP4QUOTA拡張機能の一部です。

IMAP4.getquotaroot(mailbox)

名前付きメールボックスのquota rootsのリストを取得します。 このメソッドは、rfc2087で定義されているIMAP4QUOTA拡張機能の一部です。

IMAP4.list([directory[, pattern]])

パターンに一致するディレクトリのメールボックス名を一覧表示します。 ディレクトリはデフォルトで最上位のメールフォルダになり、パターンはデフォルトで何にでも一致します。 返されるデータには、LIST応答のリストが含まれています。

IMAP4.login(user, password)

プレーンテキストのパスワードを使用してクライアントを識別します。 パスワードが引用されます。

IMAP4.login_cram_md5(user, password)

パスワードを保護するためにクライアントを識別するときに、CRAM-MD5認証の使用を強制します。 サーバーCAPABILITYの応答にフレーズAUTH=CRAM-MD5が含まれている場合にのみ機能します。

IMAP4.logout()

サーバーへの接続をシャットダウンします。 サーバーBYEの応答を返します。

バージョン3.8で変更：メソッドはサイレントに任意の例外を無視しなくなりました。

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

サブスクライブされたメールボックス名をディレクトリマッチングパターンで一覧表示します。 directory はデフォルトで最上位ディレクトリになり、 pattern はデフォルトで任意のメールボックスに一致します。 返されるデータは、メッセージ部分のエンベロープとデータのタプルです。

IMAP4.myrights(mailbox)

メールボックスのACLを表示する（つまり、 私がメールボックスに対して持っている権利）。

IMAP4.namespace()

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

IMAP4.noop()

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

IMAP4.open(host, port)

ホストのポートへのソケットを開きます。 このメソッドは、 IMAP4 コンストラクターによって暗黙的に呼び出されます。 このメソッドによって確立された接続オブジェクトは、 IMAP4.read（）、 IMAP4.readline（）、 IMAP4.send（）、および[ X147X] IMAP4.shutdown（）メソッド。 このメソッドをオーバーライドできます。

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

メッセージの切り捨てられた部分をフェッチします。 返されるデータは、メッセージ部分のエンベロープとデータのタプルです。

IMAP4.proxyauth(user)

認証を user と想定します。 権限のある管理者が任意のユーザーのメールボックスにプロキシできるようにします。

IMAP4.read(size)

リモートサーバーから size バイトを読み取ります。 このメソッドをオーバーライドできます。

IMAP4.readline()

リモートサーバーから1行を読み取ります。 このメソッドをオーバーライドできます。

IMAP4.recent()

サーバーに更新を要求します。 新しいメッセージがない場合、返されるデータはNoneです。それ以外の場合、RECENT応答の値です。

IMAP4.rename(oldmailbox, newmailbox)

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

IMAP4.response(code)

受信した場合は応答コード、またはNoneのデータを返します。 通常のタイプの代わりに、指定されたコードを返します。

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

一致するメッセージのメールボックスを検索します。 charset はNoneの場合があります。その場合、サーバーへの要求でCHARSETは指定されません。 IMAPプロトコルでは、少なくとも1つの基準を指定する必要があります。 サーバーがエラーを返すと、例外が発生します。 enable（）コマンドを使用してUTF8=ACCEPT機能を有効にした場合は、 charset をNoneにする必要があります。

例：

# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')

IMAP4.select(mailbox='INBOX', readonly=False)

メールボックスを選択します。 返されるデータは、メールボックス（EXISTS応答）内のメッセージの数です。 デフォルトのメールボックスは'INBOX'です。 読み取り専用フラグが設定されている場合、メールボックスへの変更は許可されません。

IMAP4.send(data)

dataをリモートサーバーに送信します。 このメソッドをオーバーライドできます。

IMAP4.setacl(mailbox, who, what)

メールボックスにACLを設定します。 この方法は非標準ですが、Cyrusサーバーでサポートされています。

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

メールボックスにANNOTATIONを設定します。 この方法は非標準ですが、Cyrusサーバーでサポートされています。

IMAP4.setquota(root, limits)

quota root のリソース limits を設定します。 このメソッドは、rfc2087で定義されているIMAP4QUOTA拡張機能の一部です。

IMAP4.shutdown()

openで確立された接続を閉じます。 このメソッドは、 IMAP4.logout（）によって暗黙的に呼び出されます。 このメソッドをオーバーライドできます。

IMAP4.socket()

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

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

sortコマンドは、searchの変形であり、結果のソートセマンティクスを備えています。 返されるデータには、一致するメッセージ番号のスペースで区切られたリストが含まれています。

ソートには、 search_criterion 引数の前に2つの引数があります。 sort_criteria の括弧で囲まれたリスト、および検索 charset 。 searchとは異なり、 charset 引数の検索は必須であることに注意してください。 uid searchがsearchに対応するのと同じように、sortに対応するuid sortコマンドもあります。 sortコマンドは、最初に、検索条件内の文字列の解釈にcharset引数を使用して、指定された検索条件に一致するメッセージをメールボックスで検索します。 次に、一致するメッセージの数を返します。

これはIMAP4rev1拡張コマンドです。

IMAP4.starttls(ssl_context=None)

STARTTLSコマンドを送信します。 ssl_context 引数はオプションであり、 ssl.SSLContext オブジェクトである必要があります。 これにより、IMAP接続で暗号化が有効になります。 ベストプラクティスについては、セキュリティに関する考慮事項をお読みください。

バージョン3.2の新機能。

バージョン3.4で変更：このメソッドは、 ssl.SSLContext.check_hostname および Server Name Indication によるホスト名チェックをサポートするようになりました（ ssl.HAS_SNI を参照） ）。

IMAP4.status(mailbox, names)

メールボックスの名前付きステータス条件を要求します。

IMAP4.store(message_set, command, flag_list)

メールボックス内のメッセージのフラグ処理を変更します。 コマンドは、 RFC 2060 のセクション6.4.6で、「FLAGS」、「+ FLAGS」、または「-FLAGS」のいずれかとして指定されています。 「.SILENT」のサフィックス。

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

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

ノート

']'を含むフラグ（例：「[test]」）を作成すると、 RFC 3501 （IMAPプロトコル）に違反します。 ただし、imaplibはこれまでそのようなタグの作成を許可しており、Gmailなどの一般的なIMAPサーバーはそのようなフラグを受け入れて生成します。 このようなタグを作成するPython以外のプログラムもあります。 これはRFC違反であり、IMAPクライアントとサーバーは厳密であると想定されていますが、それでもimaplibは下位互換性の理由からそのようなタグの作成を許可し続け、Python 3.6以降、サーバーから送信された場合はタグを処理します。実際の互換性を向上させます。

IMAP4.subscribe(mailbox)

新しいメールボックスを購読します。

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

threadコマンドは、searchの変形であり、結果のスレッドセマンティクスを備えています。 返されるデータには、スペースで区切られたスレッドメンバーのリストが含まれています。

スレッドメンバーは、スペースで区切られた0個以上のメッセージ番号で構成され、連続する親と子を示します。

スレッドには、 search_criterion 引数の前に2つの引数があります。 threading_algorithm 、および検索 charset 。 searchとは異なり、 charset 引数の検索は必須であることに注意してください。 uid searchがsearchに対応するのと同じように、threadに対応するuid threadコマンドもあります。 threadコマンドは、最初に、検索条件内の文字列の解釈にcharset引数を使用して、指定された検索条件に一致するメッセージをメールボックスで検索します。 次に、指定されたスレッドアルゴリズムに従ってスレッド化された一致するメッセージを返します。

これはIMAP4rev1拡張コマンドです。

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

メッセージ番号ではなく、UIDで識別されるメッセージを使用してコマンド引数を実行します。 コマンドに適切な応答を返します。 少なくとも1つの引数を指定する必要があります。 何も指定されていない場合、サーバーはエラーを返し、例外が発生します。

IMAP4.unsubscribe(mailbox)

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

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

CAPABILITY応答でサーバーから通知される単純な拡張コマンドを許可します。

IMAP4 のインスタンスでは、次の属性が定義されています。

IMAP4.PROTOCOL_VERSION

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

IMAP4.debug

デバッグ出力を制御する整数値。 初期化値は、モジュール変数Debugから取得されます。 3より大きい値は、各コマンドをトレースします。

IMAP4.utf8_enabled

通常はFalseですが、UTF8=ACCEPT機能に対して enable（）コマンドが正常に発行されると、Trueに設定されるブール値。

バージョン3.5の新機能。

IMAP4の例

メールボックスを開き、すべてのメッセージを取得して出力する最小限の例（エラーチェックなし）を次に示します。

import getpass, imaplib

M = imaplib.IMAP4()
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()