SMTP 對象?

一個(gè) SMTP 實(shí)例擁有以下方法：

SMTP.set_debuglevel(level)?

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

在 3.5 版更改: 添調試級別 2 。

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

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

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

在正常操作中，應該沒(méi)有必要明確地調用這個(gè)方法。它被用來(lái)實(shí)現其他方法，對于測試私有擴展可能很有用。

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

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

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

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

SMTP.helo(name='')?

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

在正常操作中，應該沒(méi)有必要明確調用這個(gè)方法。它將在必要時(shí)被 sendmail() 隱式調用。

SMTP.ehlo(name='')?

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

除非你想在發(fā)送郵件前使用 has_extn() ，否則應該沒(méi)有必要明確調用這個(gè)方法。 它將在必要時(shí)被 sendmail() 隱式調用。

SMTP.ehlo_or_helo_if_needed()?

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

SMTPHeloError

服務(wù)器沒(méi)有正確回復 HELO 問(wèn)候。

SMTP.has_extn(name)?

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

SMTP.verify(address)?

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

備注

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

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

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

SMTPHeloError

服務(wù)器沒(méi)有正確回復 HELO 問(wèn)候。

SMTPAuthenticationError

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

SMTPNotSupportedError

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

SMTPException

未找到適當的認證方法。

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

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

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

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

為指定的認證機制 mechanism 發(fā)送 SMTP AUTH 命令，并通過(guò) authobject 處理回復響應。

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

authobject 必須是接受一個(gè)可選的單獨參數的可調用對象:

data = authobject(challenge=None)

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

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

SMTP 類(lèi)提供的 authobjects 針對 CRAM-MD5, PLAIN 和 LOGIN 等機制；它們的名稱(chēng)分別是 SMTP.auth_cram_md5, SMTP.auth_plain 和 SMTP.auth_login。 它們都要求將 user 和 password 這兩個(gè) SMTP 實(shí)例屬性設為適當的值。

用戶(hù)代碼通常不需要直接調用 auth，而是調用 login() 方法，它將按上述順序依次嘗試上述每一種機制。 auth 被公開(kāi)以便輔助實(shí)現 smtplib 沒(méi)有（或尚未）直接支持的認證方法。

3.5 新版功能.

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

將 SMTP 連接設為 TLS (傳輸層安全) 模式。 后續的所有 SMTP 命令都將被加密。 你應當隨即再次調用 ehlo()。

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

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

如果這個(gè)會(huì )話(huà)中沒(méi)有先前的 EHLO or HELO 命令，該方法會(huì )首先嘗試 ESMTP EHLO。

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

SMTPHeloError

服務(wù)器沒(méi)有正確回復 HELO 問(wèn)候。

SMTPNotSupportedError

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

RuntimeError

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

在 3.3 版更改: 增加了 context。

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

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

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

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

備注

from_addr 和 to_addrs 形參被用來(lái)構造傳輸代理所使用的消息封包。 sendmail 不會(huì )以任何方式修改消息標頭。

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

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

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

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

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

SMTPRecipientsRefused

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

SMTPHeloError

服務(wù)器沒(méi)有正確回復 HELO 問(wèn)候。

SMTPSenderRefused

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

SMTPDataError

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

SMTPNotSupportedError

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

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

在 3.2 版更改: msg 可以為字節串。

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

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

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

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

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

3.2 新版功能.

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

SMTP.quit()?

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

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

SMTP 示例?

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

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()