smtplib --- SMTP 協(xié)議客戶端?

SMTP 對象?

一個 SMTP 實例擁有以下方法：

SMTP.set_debuglevel(level)?

設(shè)置調(diào)試輸出級別。 如果 level 的值為 1 或 True ，就會產(chǎn)生連接的調(diào)試信息，以及所有發(fā)送和接收服務(wù)器的信息。 如果 level 的值為 2 ，則這些信息會被加上時間戳。

在 3.5 版更改: 添調(diào)試級別 2 。

SMTP.docmd(cmd, args='')?

向服務(wù)器發(fā)送一條命令 cmd 。 可選的參數(shù) args 被簡單地串聯(lián)到命令中，用一個空格隔開。

這將返回一個由數(shù)字響應(yīng)代碼和實際響應(yīng)行組成的2元組（多行響應(yīng)被連接成一個長行）。

在正常操作中，應(yīng)該沒有必要明確地調(diào)用這個方法。它被用來實現(xiàn)其他方法，對于測試私有擴展可能很有用。

如果在等待回復(fù)的過程中，與服務(wù)器的連接丟失， SMTPServerDisconnected 將被觸發(fā)。

SMTP.connect(host='localhost', port=0)?

連接到某個主機的某個端口。默認(rèn)是連接到 localhost 的標(biāo)準(zhǔn) SMTP 端口（25）上。如果主機名以冒號 (':') 結(jié)尾，后跟數(shù)字，則該后綴將被刪除，且數(shù)字將視作要使用的端口號。如果在實例化時指定了 host，則構(gòu)造函數(shù)會自動調(diào)用本方法。返回包含響應(yīng)碼和響應(yīng)消息的 2 元組，它們由服務(wù)器在其連接響應(yīng)中發(fā)送。

觸發(fā)一個 auditing event smtplib.connect，其參數(shù)為 self ， host ， port 。

SMTP.helo(name='')?

使用 HELO 向 SMTP 服務(wù)器表明自己的身份。 hostname 參數(shù)默認(rèn)為本地主機的完全合格域名。服務(wù)器返回的消息被存儲為對象的 helo_resp 屬性。

在正常操作中，應(yīng)該沒有必要明確調(diào)用這個方法。它將在必要時被 sendmail() 隱式調(diào)用。

SMTP.ehlo(name='')?

使用 EHLO 向 ESMTP 服務(wù)器表明自己的身份。 hostname 參數(shù)默認(rèn)為本地主機的完全合格域名。 檢查 ESMTP 選項的響應(yīng)，并存儲它們供 has_extn() 使用。同時設(shè)置幾個信息屬性：服務(wù)器返回的消息被存儲為 ehlo_resp 屬性， does_esmtp 根據(jù)服務(wù)器是否支持 ESMTP 被設(shè)置為 True 或 False ，而 esmtp_features 將是一個字典，包含這個服務(wù)器支持的 SMTP 服務(wù)擴展的名稱，以及它們的參數(shù)（如果有）。

除非你想在發(fā)送郵件前使用 has_extn() ，否則應(yīng)該沒有必要明確調(diào)用這個方法。 它將在必要時被 sendmail() 隱式調(diào)用。

SMTP.ehlo_or_helo_if_needed()?

如果這個會話中沒有先前的 EHLO 或 HELO 命令，該方法會調(diào)用 ehlo() 和/或 helo() 。它首先嘗試 ESMTP EHLO 。

SMTPHeloError

服務(wù)器沒有正確回復(fù) HELO 問候。

SMTP.has_extn(name)?

如果 name 在服務(wù)器返回的 SMTP 服務(wù)擴展集合中，返回 True ，否則為 False 。大小寫被忽略。

SMTP.verify(address)?

使用 SMTP VRFY 檢查此服務(wù)器上的某個地址是否有效。 如果用戶地址有效則返回一個由代碼 250 和完整 RFC 822 地址（包括人名）組成的元組。 否則返回 400 或更大的 SMTP 錯誤代碼以及一個錯誤字符串。

備注

許多網(wǎng)站都禁用 SMTP VRFY 以阻止垃圾郵件。

SMTP.login(user, password, *, initial_response_ok=True)?

登錄到一個需要認(rèn)證的 SMTP 服務(wù)器。 參數(shù)是用于認(rèn)證的用戶名和密碼。 如果會話在之前沒有執(zhí)行過 EHLO 或 HELO 命令，此方法會先嘗試 ESMTP EHLO。 如果認(rèn)證成功則此方法將正常返回，否則可能引發(fā)以下異常:

SMTPHeloError

服務(wù)器沒有正確回復(fù) HELO 問候。

SMTPAuthenticationError

服務(wù)器不接受所提供的用戶名/密碼組合。

SMTPNotSupportedError

服務(wù)器不支持 AUTH 命令。

SMTPException

未找到適當(dāng)?shù)恼J(rèn)證方法。

smtplib 所支持的每種認(rèn)證方法只要被服務(wù)器聲明支持就會被依次嘗試。 請參閱 auth() 獲取受支持的認(rèn)證方法列表。 initial_response_ok 會被傳遞給 auth()。

可選的關(guān)鍵字參數(shù) initial_response_ok 對于支持它的認(rèn)證方法，是否可以與 AUTH 命令一起發(fā)送 RFC 4954 中所規(guī)定的“初始響應(yīng)”，而不是要求回復(fù)/響應(yīng)。

在 3.5 版更改: 可能會引發(fā) SMTPNotSupportedError，并添加 initial_response_ok 形參。

SMTP.auth(mechanism, authobject, *, initial_response_ok=True)?

為指定的認(rèn)證機制 mechanism 發(fā)送 SMTP AUTH 命令，并通過 authobject 處理回復(fù)響應(yīng)。

mechanism 指定要使用何種認(rèn)證機制作為 AUTH 命令的參數(shù)；可用的值是在 esmtp_features 的 auth 元素中列出的內(nèi)容。

authobject 必須是接受一個可選的單獨參數(shù)的可調(diào)用對象:

data = authobject(challenge=None)

如果可選的關(guān)鍵字參數(shù) initial_response_ok 為真值，則將先不帶參數(shù)地調(diào)用 authobject()。 它可以返回 RFC 4954 "初始響應(yīng)" ASCII str，其內(nèi)容將被編碼并使用下述的 AUTH 命令來發(fā)送。 如果 authobject() 不支持初始響應(yīng)（例如由于要求一個回復(fù)），它應(yīng)當(dāng)將 None 作為附帶 challenge=None 調(diào)用的返回值。 如果 initial_response_ok 為假值，則 authobject() 將不會附帶 None 被首先調(diào)用。

如果初始響應(yīng)檢測返回了 None，或者如果 initial_response_ok 為假值，則將調(diào)用 authobject() 來處理服務(wù)器的回復(fù)響應(yīng)；它所傳遞的 challenge 參數(shù)將為一個 bytes。 它應(yīng)當(dāng)返回用 base64 進(jìn)行編碼的 ASCII str data 并發(fā)送給服務(wù)器。

SMTP 類提供的 authobjects 針對 CRAM-MD5, PLAIN 和 LOGIN 等機制；它們的名稱分別是 SMTP.auth_cram_md5, SMTP.auth_plain 和 SMTP.auth_login。 它們都要求將 user 和 password 這兩個 SMTP 實例屬性設(shè)為適當(dāng)?shù)闹怠?/p>

用戶代碼通常不需要直接調(diào)用 auth，而是調(diào)用 login() 方法，它將按上述順序依次嘗試上述每一種機制。 auth 被公開以便輔助實現(xiàn) smtplib 沒有（或尚未）直接支持的認(rèn)證方法。

3.5 新版功能.

SMTP.starttls(keyfile=None, certfile=None, context=None)?

將 SMTP 連接設(shè)為 TLS (傳輸層安全) 模式。 后續(xù)的所有 SMTP 命令都將被加密。 你應(yīng)當(dāng)隨即再次調(diào)用 ehlo()。

如果提供了 keyfile 和 certfile，它們會被用來創(chuàng)建 ssl.SSLContext。

可選的 context 形參是一個 ssl.SSLContext 對象；它是使用密鑰文件和證書的替代方式，如果指定了該形參則 keyfile 和 certfile 都應(yīng)為 None。

如果這個會話中沒有先前的 EHLO or HELO 命令，該方法會首先嘗試 ESMTP EHLO。

3.6 版后已移除: keyfile 和 certfile 已棄用并轉(zhuǎn)而推薦 context。 請改用 ssl.SSLContext.load_cert_chain() 或讓 ssl.create_default_context() 為你選擇系統(tǒng)所信任的 CA 證書。

SMTPHeloError

服務(wù)器沒有正確回復(fù) HELO 問候。

SMTPNotSupportedError

服務(wù)器不支持 STARTTLS 擴展。

RuntimeError

SSL/TLS 支持在你的 Python 解釋器上不可用。

在 3.3 版更改: 增加了 context。

在 3.4 版更改: 此方法現(xiàn)在支持使用 SSLContext.check_hostname 和 服務(wù)器名稱指示符 (參見 HAS_SNI) 進(jìn)行主機名檢查。

在 3.5 版更改: 因缺少 STARTTLS 支持而引發(fā)的錯誤現(xiàn)在是 SMTPNotSupportedError 子類而不是 SMTPException 基類。

SMTP.sendmail(from_addr, to_addrs, msg, mail_options=(), rcpt_options=())?

發(fā)送郵件。必要參數(shù)是一個 RFC 822 發(fā)件地址字符串，一個 RFC 822 收件地址字符串列表（裸字符串將被視為含有 1 個地址的列表），以及一個消息字符串。調(diào)用者可以將 ESMTP 選項列表（如 8bitmime）作為 mail_options 傳入，用于 MAIL FROM 命令。需要與所有 RCPT 命令一起使用的 ESMTP 選項（如 DSN 命令）可以作為 rcpt_options 傳入。（如果需要對不同的收件人使用不同的 ESMTP 選項，則必須使用底層的方法來發(fā)送消息，如 mail(), rcpt() 和 data()。）

備注

from_addr 和 to_addrs 形參被用來構(gòu)造傳輸代理所使用的消息封包。 sendmail 不會以任何方式修改消息標(biāo)頭。

msg 可以是一個包含 ASCII 范圍內(nèi)字符的字符串，或是一個字節(jié)串。 字符串會使用 ascii 編解碼器編碼為字節(jié)串，并且單獨的 \r 和 \n 字符會被轉(zhuǎn)換為 \r\n 字符序列。 字節(jié)串則不會被修改。

如果在此之前本會話沒有執(zhí)行過 EHLO 或 HELO 命令，此方法會先嘗試 ESMTP EHLO。 如果服務(wù)器執(zhí)行了 ESMTP，消息大小和每個指定的選項將被傳遞給它（如果指定的選項屬于服務(wù)器聲明的特性集）。 如果 EHLO 失敗，則將嘗試 HELO 并屏蔽 ESMTP 選項。

如果郵件被至少一個接收方接受則此方法將正常返回。 在其他情況下它將引發(fā)異常。 也就是說，如果此方法沒有引發(fā)異常，則應(yīng)當(dāng)會有人收到你的郵件。 如果此方法沒有引發(fā)異常，它將返回一個字典，其中的條目對應(yīng)每個拒絕的接收方。 每個條目均包含由服務(wù)器發(fā)送的 SMTP 錯誤代碼和相應(yīng)錯誤消息所組成的元組。

如果 SMTPUTF8 包括在 mail_options 中，并且被服務(wù)器所支持，則 from_addr 和 to_addrs 可能包含非 ASCII 字符。

此方法可能引發(fā)以下異常:

SMTPRecipientsRefused

所有收件人都被拒絕。 無人收到郵件。 該異常的 recipients 屬性是一個字典，其中有被拒絕收件人的信息（類似于至少有一個收件人接受郵件時所返回的信息）。

SMTPHeloError

服務(wù)器沒有正確回復(fù) HELO 問候。

SMTPSenderRefused

服務(wù)器不接受 from_addr。

SMTPDataError

服務(wù)器回復(fù)了一個意外的錯誤代碼（而不是拒絕收件人）。

SMTPNotSupportedError

在 mail_options 中給出了 SMTPUTF8 但是不被服務(wù)器所支持。

除非另有說明，即使在引發(fā)異常之后連接仍將被打開。

在 3.2 版更改: msg 可以為字節(jié)串。

在 3.5 版更改: 增加了 SMTPUTF8 支持，并且如果指定了 SMTPUTF8 但是不被服務(wù)器所支持則可能會引發(fā) SMTPNotSupportedError。

SMTP.send_message(msg, from_addr=None, to_addrs=None, mail_options=(), rcpt_options=())?

本方法是一種快捷方法，用于帶著消息調(diào)用 sendmail()，消息由 email.message.Message 對象表示。參數(shù)的含義與 sendmail() 中的相同，除了 msg，它是一個 Message 對象。

如果 from_addr 為 None 或 to_addrs 為 None，那么``send_message``將根據(jù) RFC 5322，從 msg 頭部提取地址填充下列參數(shù)：如果頭部存在 Sender 字段，則用它填充 from_addr，不存在則用 From 字段填充 from_addr。to_addrs 組合了 msg 中的 To, Cc 和 Bcc 字段的值（字段存在的情況下）。如果一組 Resent-* 頭部恰好出現(xiàn)在 message 中，那么就忽略常規(guī)的頭部，改用 Resent-* 頭部。如果 message 包含多組 Resent-* 頭部，則引發(fā) ValueError，因為無法明確檢測出哪一組 Resent- 頭部是最新的。

send_message 使用 BytesGenerator 來序列化 msg，且將 \r\n 作為 linesep，并調(diào)用 sendmail() 來傳輸序列化后的結(jié)果。無論 from_addr 和 to_addrs 的值為何，send_message 都不會傳輸 msg 中可能出現(xiàn)的 Bcc 或 Resent-Bcc 頭部。如果 from_addr 和 to_addrs 中的某個地址包含非 ASCII 字符，且服務(wù)器沒有聲明支持 SMTPUTF8，則引發(fā) SMTPNotSupported 錯誤。如果服務(wù)器支持，則 Message 將按新克隆的 policy 進(jìn)行序列化，其中的 utf8 屬性被設(shè)置為 True，且 SMTPUTF8 和 BODY=8BITMIME 被添加到 mail_options 中。

3.2 新版功能.

3.5 新版功能: 支持國際化地址 (SMTPUTF8)。

SMTP.quit()?

終結(jié) SMTP 會話并關(guān)閉連接。 返回 SMTP QUIT 命令的結(jié)果。

與標(biāo)準(zhǔn) SMTP/ESMTP 命令 HELP, RSET, NOOP, MAIL, RCPT 和 DATA 對應(yīng)的低層級方法也是受支持的。 通常不需要直接調(diào)用這些方法，因此它們沒有被寫入本文檔。 相關(guān)細(xì)節(jié)請參看模塊代碼。

SMTP 示例?

這個例子提示用戶輸入消息封包所需的地址 ('To' 和 'From' 地址)，以及所要封包的消息。 請注意包括在消息中的標(biāo)頭必須包括在輸入的消息中；這個例子不對 RFC 822 標(biāo)頭進(jìn)行任何處理。 特別地，'To' 和 'From' 地址必須顯式地包括在消息標(biāo)頭中。

import smtplib

def prompt(prompt):
    return 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 True:
    try:
        line = input()
    except EOFError:
        break
    if not line:
        break
    msg = msg + line

print("Message length is", len(msg))

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