目錄

名稱

Net::SMTP - 簡單郵件傳輸協定客戶端

語法

use Net::SMTP;

# Constructors
$smtp = Net::SMTP->new('mailhost');
$smtp = Net::SMTP->new('mailhost', Timeout => 60);

說明

此模組實作了 SMTP 和 ESMTP 協定的客戶端介面，讓 perl5 應用程式可以與 SMTP 伺服器通訊。此文件假設您熟悉 RFC2821 中所述的 SMTP 協定概念。安裝 IO::Socket::SSL 後，它也支援隱式和明確的 TLS 加密，亦即 SMTPS 或 SMTP+STARTTLS。

Net::SMTP 類別是 Net::Cmd 的子類別，以及（視可用性而定）IO::Socket::IP、IO::Socket::INET6 或 IO::Socket::INET 的子類別。

類別方法

new([$host][, %options])

這是建立新的 Net::SMTP 物件的建構函式。$host 是需要建立 SMTP 連線的遠端主機名稱。

如果發生錯誤，將會傳回 undef，而 $@ 會包含錯誤原因。

$host 是選用的。如果未提供 $host，則可以將其作為下方所述的 Host 選項傳遞。如果兩者都沒有提供，則會使用 Net::Config 中指定的 SMTP_Hosts。

%options 以雜湊方式傳遞，使用金鑰和值對。可能的選項為

您好 - SMTP 要求您識別自己。此選項指定傳遞為您的郵件網域的字串。如果未提供，將使用 localhost.localdomain。

SendHello - 如果為 false，則在建構物件時通常傳送的 EHLO（或 HELO）指令將不會傳送。在這種情況下，必須改為呼叫 hello() 手動傳送指令。

主機 - 要連線的 SMTP 主機。它可以是單一純量（主機名稱[:port]），如 IO::Socket::INET 中 PeerAddr 選項所定義，或參考要依序嘗試的主機陣列。 "host" 方法將傳回用於連線至主機的值。格式 - IO::Socket::INET 新方法的 PeerHost。

埠 - 要連線的埠。預設值 - 一般 SMTP 為 25，立即 SSL 為 465。

SSL - 如果連線應從開始就使用 SSL，而不是稍後使用 starttls 升級。您可以使用 IO::Socket::SSL 中記載的 SSL 引數，但通常它會自動使用正確的引數。

LocalAddr 和 LocalPort - 這些參數直接傳遞給 IO::Socket，以允許將 socket 繫結到特定的本機位址和埠。

網域 - 此參數直接傳遞給 IO::Socket，即使 IO::Socket::IP 用作超類別，也能強制執行 IPv4 連線。或者可以使用 Family。

逾時 - 等待 SMTP 伺服器回應的最長時間（秒）（預設值：120）

ExactAddresses - 如果為 true，則所有 $address 引數都必須符合 RFC2822 中 addr-spec 的定義。如果未提供或為 false，Net::SMTP 將嘗試從傳遞的值中擷取位址。

偵錯 - 啟用偵錯資訊

範例

$smtp = Net::SMTP->new('mailhost',
                       Hello => 'my.mail.domain',
                       Timeout => 30,
                       Debug   => 1,
                      );

# the same
$smtp = Net::SMTP->new(
                       Host => 'mailhost',
                       Hello => 'my.mail.domain',
                       Timeout => 30,
                       Debug   => 1,
                      );

# the same with direct SSL
$smtp = Net::SMTP->new('mailhost',
                       Hello => 'my.mail.domain',
                       Timeout => 30,
                       Debug   => 1,
                       SSL     => 1,
                      );

# Connect to the default server from Net::config
$smtp = Net::SMTP->new(
                       Hello => 'my.mail.domain',
                       Timeout => 30,
                      );

物件方法

除非另有說明，否則所有方法都傳回 true 或 false 值，其中 true 表示操作成功。當方法指出它傳回值時，失敗將傳回為 undef 或空清單。

Net::SMTP 從 Net::Cmd 繼承，因此除了本文檔中記載的方法之外，也可以使用 Net::Cmd 中定義的方法將指令傳送至遠端 SMTP 伺服器。

banner()

傳回伺服器在建立初始連線時回覆的橫幅訊息。

domain()

傳回遠端 SMTP 伺服器在連線期間識別自己的網域。

hello($domain)

使用 EHLO 指令（如果 EHLO 失敗，則使用 HELO）告知遠端伺服器您正在使用的郵件網域。由於在建構 Net::SMTP 物件時會自動呼叫此方法，因此使用者通常不必手動呼叫它。

host()

傳回建構函式使用的值，並傳遞給 IO::Socket::INET 以連線至主機。

etrn($domain)

要求執行給定 $domain 的佇列。

starttls(%sslargs)

將現有的純文字連線升級為 SSL。您可以使用 IO::Socket::SSL 中記載的 SSL 引數，但它通常會使用正確的引數。

auth($username, $password)
auth($sasl)

嘗試 SASL 驗證。需要 Authen::SASL 模組。第一個表單使用給定的使用者名稱和密碼建構新的 Authen::SASL 物件；第二個表單使用給定的 Authen::SASL 物件。

mail($address[, %options])
send($address)
send_or_mail($address)
send_and_mail($address)

傳送適當的指令至伺服器 MAIL、SEND、SOML 或 SAML。$address 是寄件者的地址。這會啟動訊息傳送。應針對要傳送訊息的每個地址呼叫 recipient 方法。

mail 方法可以採用一些額外的 ESMTP %options，這些選項以雜湊方式傳遞，使用金鑰和值對。可能的選項包括

Size        => <bytes>
Return      => "FULL" | "HDRS"
Bits        => "7" | "8" | "binary"
Transaction => <ADDRESS>
Envelope    => <ENVID>     # xtext-encodes its argument
ENVID       => <ENVID>     # similar to Envelope, but expects argument encoded
XVERP       => 1
AUTH        => <submitter> # encoded address according to RFC 2554

Return 和 Envelope 參數用於 DSN（傳送狀態通知）。

AUTH 選項中的提交者地址預期採用 RFC 2554 所需的格式，以 RFC2821 引號形式和 xtext 編碼，或 <>。

reset()

重設伺服器的狀態。這可以在訊息啟動後，但在傳送任何資料之前呼叫，以取消訊息傳送。

recipient($address[, $address[, ...]][, %options])

通知伺服器應將目前的訊息傳送至所有給定的地址。每個地址會作為一個獨立的指令傳送至伺服器。如果傳送任何地址導致失敗，則會中止處理並傳回 false 值。使用者可以自行決定是否呼叫 reset。

recipient 方法也可以傳遞其他大小寫敏感的 %options 作為匿名雜湊，使用鍵值對。可能的選項為

Notify  => ['NEVER'] or ['SUCCESS','FAILURE','DELAY']  (see below)
ORcpt   => <ORCPT>
SkipBad => 1        (to ignore bad addresses)

如果 SkipBad 為 true，則 recipient 在遇到錯誤的地址時不會傳回錯誤，而且會傳回成功地址的陣列。

$smtp->recipient($recipient1,$recipient2);  # Good
$smtp->recipient($recipient1,$recipient2, { SkipBad => 1 });  # Good
$smtp->recipient($recipient1,$recipient2, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
@goodrecips=$smtp->recipient(@recipients, { Notify => ['FAILURE'], SkipBad => 1 });  # Good
$smtp->recipient("$recipient,$recipient2"); # BAD

Notify 用於要求傳送狀態通知 (DSN)，但您的 SMTP/ESMTP 服務可能不會尊重此要求，具體取決於其版本和您網站的 SMTP 組態。

省略 Notify 選項通常會將 SMTP 服務預設為其預設行為，等同於僅 ['FAILURE'] 通知，但這也可能取決於您網站的 SMTP 組態。

如果在 Notify 選項中使用 NEVER 關鍵字，則它必須單獨出現，而且「要求在任何情況下都不會傳回 DSN 給寄件者」。

{Notify => ['NEVER']}

$smtp->recipient(@recipients, { Notify => ['NEVER'], SkipBad => 1 });  # Good

您可以在匿名陣列參考中使用這些三個值 'SUCCESS'、'FAILURE'、'DELAY' 的任何組合，如 RFC3461 所定義（請參閱 https://www.ietf.org/rfc/rfc3461.txt 以取得更多資訊。注意：本主題中的引號來自同一處）。

Notify 參數 'SUCCESS' 或 'FAILURE'「要求在傳送成功或傳送失敗時發出 DSN」。

Notify 參數 'DELAY'「表示寄件者願意接收延遲的 DSN。如果訊息傳送延遲一段異常的時間（由訊息延遲所在訊息傳輸代理 (MTA) 決定），但無法確定最後的傳送狀態（成功或失敗），則可能會發出延遲的 DSN。NOTIFY 參數中沒有 DELAY 關鍵字表示要求在任何情況下都不會發出「延遲」DSN」。

{Notify => ['SUCCESS','FAILURE','DELAY']}

$smtp->recipient(@recipients, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good

根據 RFC3461，ORcpt 也是 SMTP DSN 延伸的一部分。它用於傳遞郵件最初傳送到的原始收件者。產生 DSN 的機器會使用此地址通知寄件者，因為他無法知道收件者是否會被郵件伺服器改寫。預期它會採用 RFC3461 所要求的格式，x 文字編碼。

to($address[, $address[, ...]])
cc($address[, $address[, ...]])
bcc($address[, $address[, ...]])

recipient 的同義詞。

data([$data])

啟動傳送目前訊息的資料。

$data 可能會參考一個清單或一個清單，且呼叫者必須將其編碼為任何編碼所需的八位組，例如使用 Encode 模組的 encode() 函式。

如果指定 $data 的內容和終止字串 ".\r\n" 會傳送至伺服器。如果資料被接受，結果會為真。

如果未指定 $data，結果會指出伺服器希望傳送資料。資料必須使用 Net::Cmd 中所述的 datasend 和 dataend 方法傳送。

bdat($data)
bdatlast($data)

使用 RFC1830 中定義的資料分塊服務延伸的替代 $data 指令「BDAT」，以有效率的方式傳送大型 MIME 訊息。

expand($address)

要求伺服器展開指定的地址，傳回包含從伺服器讀取的文字的陣列。

verify($address)

驗證 $address 是否為合法的郵寄地址。

大多數網站通常會在 SMTP 服務設定中停用此功能。使用 new() 下的「Debug => 1」選項查看是否已停用。

help([$subject])

要求伺服器提供說明文字。傳回文字或在失敗時傳回未定義

quit()

傳送 QUIT 指令至遠端 SMTP 伺服器並關閉 socket 連線。

can_inet6()

傳回我們是否可以使用 IPv6。

can_ssl()

傳回我們是否可以使用 SSL。

地址

Net::SMTP 嘗試使用傳遞的地址進行 DWIM。例如，應用程式可能會從電子郵件中擷取 From: 行並將其傳遞至郵件()。雖然這可能會成功，但並不建議這麼做。應用程式實際上應該使用類似 Mail::Address 的模組來擷取郵件地址並傳遞。

如果傳遞 ExactAddresses 至建構函式，則地址應該是有效的 rfc2821 引號地址，儘管 Net::SMTP 會接受以尖括號包圍的地址。

funny user@domain      WRONG
"funny user"@domain    RIGHT, recommended
<"funny user"@domain>  OK

範例

此範例會列印稱為 mailhost 的 SMTP 伺服器的郵件網域名稱

#!/usr/local/bin/perl -w

use Net::SMTP;

$smtp = Net::SMTP->new('mailhost');
print $smtp->domain,"\n";
$smtp->quit;

此範例會傳送一則簡短訊息給稱為 mailhost 的 SMTP 伺服器的郵件管理員

#!/usr/local/bin/perl -w

use Net::SMTP;

my $smtp = Net::SMTP->new('mailhost');

$smtp->mail($ENV{USER});
if ($smtp->to('postmaster')) {
 $smtp->data();
 $smtp->datasend("To: postmaster\n");
 $smtp->datasend("\n");
 $smtp->datasend("A simple test message\n");
 $smtp->dataend();
} else {
 print "Error: ", $smtp->message();
}

$smtp->quit;

匯出

無.

已知錯誤

請參閱 https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet。

另請參閱

Net::Cmd、IO::Socket::SSL。

作者

Graham Barr <gbarr@pobox.com>。

Steve Hay <shay@cpan.org> 現正維護 libnet，版本為 1.22_02。

版權

Copyright (C) 1995-2004 Graham Barr。保留所有權利。

Copyright (C) 2013-2016, 2020 Steve Hay。保留所有權利。

授權

此模組為自由軟體；您可以在與 Perl 相同的條款下重新散布或修改它，亦即在 GNU 通用公共授權或 Artistic 授權的條款下，如 LICENCE 檔案中所指定。

版本

版本 3.15

日期

2023 年 3 月 20 日

歷史

請參閱 Changes 檔案。