"smtplib" — SMTP プロトコルクライアント
***************************************

**ソースコード:** Lib/smtplib.py

======================================================================

"smtplib" モジュールは、SMTPまたはESMTPのリスナーデーモンを備えた任意
のインターネット上のホストにメールを送るために使用することができる
SMTPクライアント・セッション・オブジェクトを定義します。 SMTPおよび
ESMTPオペレーションの詳細は、 **RFC 821** (Simple Mail Transfer
Protocol) や **RFC 1869** (SMTP Service Extensions)を調べてください。

class smtplib.SMTP([host[, port[, local_hostname[, timeout]]]])

   An "SMTP" instance encapsulates an SMTP connection.  It has methods
   that support a full repertoire of SMTP and ESMTP operations. If the
   optional host and port parameters are given, the SMTP "connect()"
   method is called with those parameters during initialization.  If
   specified, *local_hostname* is used as the FQDN of the local host
   in the HELO/EHLO command.  Otherwise, the local hostname is found
   using "socket.getfqdn()".  If the "connect()" call returns anything
   other than a success code, an "SMTPConnectError" is raised. The
   optional *timeout* parameter specifies a timeout in seconds for
   blocking operations like the connection attempt (if not specified,
   the global default timeout setting will be used).  If the timeout
   expires, "socket.timeout" is raised.

   普通に使う場合は、初期化と接続を行ってから、 "sendmail()" と
   "quit()" メソッドを呼びます。使用例は先の方で記載しています。

   バージョン 2.6 で変更: *timeout* was added.

class smtplib.SMTP_SSL([host[, port[, local_hostname[, keyfile[, certfile[, timeout]]]]]])

   An "SMTP_SSL" instance behaves exactly the same as instances of
   "SMTP". "SMTP_SSL" should be used for situations where SSL is
   required from the beginning of the connection and using
   "starttls()" is not appropriate. If *host* is not specified, the
   local host is used. If *port* is omitted, the standard SMTP-over-
   SSL port (465) is used. *local_hostname* has the same meaning as it
   does for the "SMTP" class.  *keyfile* and *certfile* are also
   optional, and can contain a PEM formatted private key and
   certificate chain file for the SSL connection. The optional
   *timeout* parameter specifies a timeout in seconds for blocking
   operations like the connection attempt (if not specified, the
   global default timeout setting will be used).  If the timeout
   expires, "socket.timeout" is raised.

   バージョン 2.6 で追加.

class smtplib.LMTP([host[, port[, local_hostname]]])

   The LMTP protocol, which is very similar to ESMTP, is heavily based
   on the standard SMTP client. It’s common to use Unix sockets for
   LMTP, so our "connect()" method must support that as well as a
   regular host:port server.  *local_hostname* has the same meaning as
   it does for the "SMTP" class.  To specify a Unix socket, you must
   use an absolute path for *host*, starting with a 『/』.

   認証は、通常のSMTP機構を利用してサポートされています。 Unixソケット
   を利用する場合、LMTPは通常認証をサポートしたり要求したりはしません
   。しかし、あなたが必要であれば、利用することができます。

   バージョン 2.6 で追加.

このモジュールの例外には次のものがあります:

exception smtplib.SMTPException

   The base exception class for all the other exceptions provided by
   this module.

exception smtplib.SMTPServerDisconnected

   この例外はサーバが突然接続が切断されるか、"SMTP" インスタンスを生成
   する前に接続しようとした場合に送出されます。

exception smtplib.SMTPResponseException

   SMTPのエラーコードを含んだ例外のクラスです。これらの例外はSMTPサー
   バがエラーコードを返すときに生成されます。エラーコードは
   "smtp_code" 属性に格納されます。また、 "smtp_error" 属性にはエラー
   メッセージが格納されます。

exception smtplib.SMTPSenderRefused

   送信者のアドレスが弾かれたときに送出される例外です。全ての
   "SMTPResponseException" 例外に、 SMTPサーバが弾いた 『sender』 アド
   レスの文字列がセットされます。

exception smtplib.SMTPRecipientsRefused

   全ての受取人アドレスが弾かれたときに送出される例外です。各受取人の
   エラーは属性 "recipients" によってアクセス可能で、
   "SMTP.sendmail()" が返す辞書と同じ並びの辞書になっています。

exception smtplib.SMTPDataError

   SMTPサーバが、メッセージのデータを受け入れることを拒絶したときに送
   出される例外です。

exception smtplib.SMTPConnectError

   サーバへの接続時にエラーが発生したときに送出される例外です。

exception smtplib.SMTPHeloError

   サーバーが "HELO" メッセージを弾いたときに送出される例外です。

exception smtplib.SMTPAuthenticationError

   SMTP 認証が失敗しました。最もあり得るのは、サーバーがユーザ名/パス
   ワードのペアを受け付なかった事です。

参考:

  **RFC 821** - Simple Mail Transfer Protocol
     SMTP のプロトコル定義です。このドキュメントでは SMTP のモデル、操
     作手順、プロトコルの詳細についてカバーしています。

  **RFC 1869** - SMTP Service Extensions
     SMTP に対する ESMTP 拡張の定義です。このドキュメントでは、新たな
     命令による SMTP の拡張、サーバによって提供される命令を動的に発見
     する機能のサポート、およびいくつかの追加命令定義について記述して
     います。


SMTP オブジェクト
=================

"SMTP" クラスインスタンスは次のメソッドを提供します:

SMTP.set_debuglevel(level)

   Set the debug output level.  A true value for *level* results in
   debug messages for connection and for all messages sent to and
   received from the server.

SMTP.docmd(cmd[, argstring])

   Send a command *cmd* to the server.  The optional argument
   *argstring* is simply concatenated to the command, separated by a
   space.

   数値応答コードと実際の応答行 (複数の応答は 1 つの長い行に結合されま
   す) からなる 2 値タプルを返します。

   通常、このメソッドを明示的に使う必要はありません。他のメソッドを実
   装するのに使い、自分で拡張したものをテストするのに役立つかもしれま
   せん。

   応答待ちのときにサーバへの接続が切れると "SMTPServerDisconnected"
   が送出されます。

SMTP.connect([host[, port]])

   ホスト名とポート番号をもとに接続します。デフォルトはlocalhostの標準
   的なSMTPポート(25番)に接続します。もしホスト名の末尾がコロン("':'")
   で、後に番号がついている場合は、「ホスト名:ポート番号」として扱われ
   ます。このメソッドはコンストラクタにホスト名及びポート番号が指定さ
   れている場合、自動的に呼び出されます。戻り値は、この接続の応答内で
   サーバによって送信された応答コードとメッセージの2要素タプルです。

SMTP.helo([hostname])

   SMTPサーバに "HELO" コマンドで身元を示します。デフォルトでは
   hostname引数はローカルホストを指します。サーバーが返したメッセージ
   は、オブジェクトの "helo_resp" 属性に格納されます。

   通常は "sendmail()" が呼びだすため、これを明示的に呼び出す必要はあ
   りません。

SMTP.ehlo([hostname])

   "EHLO" を利用し、ESMTPサーバに身元を明かします。デフォルトでは
   hostname引数はローカルホストのFQDNです。また、ESMTPオプションのため
   に応答を調べたものは、 "has_extn()" に備えて保存されます。また、幾
   つかの情報を属性に保存します: サーバーが返したメッセージは
   "ehlo_resp" 属性に、 "does_esmtp" 属性はサーバーがESMTPをサポートし
   ているかどうかによって true か false に、 "esmtp_features" 属性は辞
   書で、サーバーが対応しているSMTP サービス拡張の名前と、もしあればそ
   のパラメータを格納します。

   メールを送信する前に "has_extn()" を使おうとしない限り、このメソッ
   ドを明示的に呼ぶ必要はないはずです。必要な場合は "sendmail()" に暗
   黙的に呼ばれます。

SMTP.ehlo_or_helo_if_needed()

   このメソッドは、現在のセッションでまだ "EHLO" か "HELO" コマンドが
   実行されていない場合、 "ehlo()" および/または "helo()" メソッドを呼
   び出します。このメソッドは先に ESMTP "EHLO" を試します。

   "SMTPHeloError"
      サーバーが "HELO" に正しく返答しませんでした。

   バージョン 2.6 で追加.

SMTP.has_extn(name)

   *name* が拡張SMTPサービスセットに含まれている場合には "True" を返し
   、そうでなければ "False" を返します。大小文字は区別されません。

SMTP.verify(address)

   "VRFY" を利用してSMTPサーバにアドレスの妥当性をチェックします。妥当
   である場合はコード250と完全な **RFC 822** アドレス (人名を含む) の
   タプルを返します。それ以外の場合は、400以上のエラーコードとエラー文
   字列を返します。

   注釈: ほとんどのサイトはスパマーの裏をかくためにSMTPの "VRFY" は
     使用不 可になっています。

SMTP.login(user, password)

   認証が必要なSMTPサーバにログインします。認証に使用する引数はユーザ
   名とパスワードです。まだセッションが無い場合は、 "EHLO" または
   "HELO" コマンドでセッションを作ります。ESMTPの場合は "EHLO" が先に
   試されます。認証が成功した場合は通常このメソッドは戻りますが、例外
   が起こった場合は以下の例外が上がります:

   "SMTPHeloError"
      サーバーが "HELO" に正しく返答しませんでした。

   "SMTPAuthenticationError"
      サーバがユーザ名/パスワードでの認証に失敗しました。

   "SMTPException"
      適当な認証方法が見付かりませんでした。

SMTP.starttls([keyfile[, certfile]])

   TLS (Transport Layer Security) モードで SMTP 接続します。続く全ての
   SMTP コマンドは暗号化されます。その後、もう一度 "ehlo()" を呼んでく
   ださい。

   *keyfile* と *certfile* が与えられた場合、 "socket" モジュールの
   "ssl()" 関数に渡されます。

   もしまだ "EHLO" か "HELO" コマンドが実行されていない場合、このメソ
   ッドは ESMTP "EHLO" を先に試します。

   バージョン 2.6 で変更.

   "SMTPHeloError"
      サーバーが "HELO" に正しく返答しませんでした。

   "SMTPException"
      サーバーが STARTTLS 拡張に対応していません。

   バージョン 2.6 で変更.

   "RuntimeError"
      実行中の Python インタプリタで、SSL/TLS サポートが利用できません
      。

SMTP.sendmail(from_addr, to_addrs, msg[, mail_options, rcpt_options])

   メールを送信します。必要な引数は **RFC 822** のfromアドレス文字列、
   **RFC 822** のtoアドレス文字列またはアドレス文字列のリスト、メッセ
   ージ文字列です。送信側は "MAIL FROM" コマンドで使用される
   *mail_options* の ESMTPオプション("8bitmime" のような)のリストを得
   るかもしれません。全ての "RCPT" コマンドで使われるべきESMTPオプショ
   ン (例えば "DSN" コマンド)は、 *rcpt_options* を通して利用すること
   ができます。(もし送信先別にESMTPオプションを使う必要があれば、メッ
   セージを送るために "mail()" 、 "rcpt()" 、 "data()" といった下位レ
   ベルのメソッドを使う必要があります。)

   注釈: The *from_addr* and *to_addrs* parameters are used to
     construct the message envelope used by the transport agents. The
     "SMTP" does not modify the message headers in any way.

   まだセッションが無い場合は、 "EHLO" または "HELO" コマンドでセッシ
   ョンを作ります。ESMTPの場合は "EHLO" が先に試されます。また、サーバ
   がESMTP対応ならば、メッセージサイズとそれぞれ指定されたオプションも
   渡します。(featureオプションがあればサーバの広告をセットします)
   "EHLO" が失敗した場合は、ESMTPオプションの無い "HELO" が試されます
   。

   このメソッドは最低でも1人の受信者にメールが受け取られたときは正常に
   戻ります。そうでない場合は例外を投げます。つまり、このメソッドが例
   外を送出しないときは誰かが送信したメールを受け取ったはずです。また
   、例外を送出しない場合は拒絶された受信者ごとに項目のある辞書を返し
   ます。各項目はサーバーが送ったSMTPエラーコードと付随するエラーメッ
   セージのタプルを持ちます。

   このメソッドは次の例外を送出することがあります:

   "SMTPRecipientsRefused"
      全ての受信を拒否され、誰にもメールが届けられませんでした。例外オ
      ブジェクトの "recipients" 属性は、受信拒否についての情報の入った
      辞書オブジェクトです。 (辞書は少なくとも一つは受信されたときに似
      ています)。

   "SMTPHeloError"
      サーバーが "HELO" に正しく返答しませんでした。

   "SMTPSenderRefused"
      サーバが *from_addr* を受理しませんでした。

   "SMTPDataError"
      サーバが予期しないエラーコードを返しました (受信拒否以外)。

   また、この他の注意として、例外が上がった後もコネクションは開いたま
   まになっています。

SMTP.quit()

   SMTPセッションを終了し、接続を閉じます。SMTP "QUIT" コマンドの結果
   を返します。

   バージョン 2.6 で変更: Return a value.

下位レベルのメソッドは標準SMTP/ESMTPコマンド "HELP" 、 "RSET" 、
"NOOP" 、 "MAIL" 、 "RCPT" 、 "DATA" に対応しています。通常これらは直
接呼ぶ必要はなく、また、ドキュメントもありません。詳細はモジュールのコ
ードを調べてください。


SMTP 使用例
===========

次の例は最低限必要なメールアドレス(『To』 と 『From』)を含んだメッセー
ジを送信するものです。この例では **RFC 822** ヘッダの加工もしていませ
ん。メッセージに含まれるヘッダは、メッセージに含まれる必要があり、特に
、明確な 『To』、と 『From』 アドレスはメッセージヘッダに含まれている
必要があります。

   import smtplib

   def prompt(prompt):
       return raw_input(prompt).strip()

   fromaddr = prompt("From: ")
   toaddrs  = prompt("To: ").split()
   print "Enter message, end with ^D (Unix) or ^Z (Windows):"

   # Add the From: and To: headers at the start!
   msg = ("From: %s\r\nTo: %s\r\n\r\n"
          % (fromaddr, ", ".join(toaddrs)))
   while 1:
       try:
           line = raw_input()
       except EOFError:
           break
       if not line:
           break
       msg = msg + line

   print "Message length is " + repr(len(msg))

   server = smtplib.SMTP('localhost')
   server.set_debuglevel(1)
   server.sendmail(fromaddr, toaddrs, msg)
   server.quit()

注釈: In general, you will want to use the "email" package’s
  features to construct an email message, which you can then convert
  to a string and send via "sendmail()"; see email: 使用例.
