内容

名称

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 以类似哈希的方式传递，使用键值对。可能的选项是

Hello - SMTP 要求您标识自己。此选项指定一个字符串作为您的邮件域。如果未提供，将使用 localhost.localdomain。

SendHello - 如果为假，则在构造对象时通常发送的 EHLO（或 HELO）命令将不会发送。在这种情况下，必须通过调用 hello() 手动发送命令。

Host - 要连接到的 SMTP 主机。它可以是单个标量（主机名[:端口]），如 IO::Socket::INET 中为 PeerAddr 选项定义的那样，也可以是包含要依次尝试的主机的数组的引用。"host" 方法将返回用于连接到主机的值。格式 - 来自 IO::Socket::INET new 方法的 PeerHost。

Port - 要连接到的端口。默认 - 25 用于普通 SMTP，465 用于立即 SSL。

SSL - 如果连接应从一开始就使用 SSL，而不是稍后使用 starttls 升级。您可以使用 IO::Socket::SSL 中记录的 SSL 参数，但它通常会使用正确的参数。

LocalAddr 和 LocalPort - 这些参数直接传递给 IO::Socket，以允许将套接字绑定到特定的本地地址和端口。

Domain - 此参数直接传递给 IO::Socket，并使即使使用 IO::Socket::IP 作为超类，也可以强制执行 IPv4 连接。或者，可以使用 Family。

Timeout - 从 SMTP 服务器等待响应的最大时间（以秒为单位）（默认：120）

ExactAddresses - 如果为真，则所有 $address 参数必须如 RFC2822 中的 addr-spec 所定义的那样。如果未提供或为假，则 Net::SMTP 将尝试从传递的值中提取地址。

Debug - 启用调试信息

示例

$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为真，则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。注意：本主题中的引号来自同一来源）。

'SUCCESS' 或 'FAILURE' 的 Notify 参数“分别请求在成功传递或传递失败时发出 DSN”。

'DELAY' 的 Notify 参数“表示发送者愿意接收延迟的 DSN。如果消息的传递延迟了异常的时间（由消息传递代理 (MTA) 确定，该代理延迟了消息），但最终的传递状态（成功或失败）无法确定，则可能会发出延迟的 DSN。NOTIFY 参数中没有 DELAY 关键字请求在任何情况下都不发出“延迟”DSN。

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

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

ORcpt 也是 RFC3461 中 SMTP DSN 扩展的一部分。它用于传递邮件最初发送到的原始收件人。生成 DSN 的机器将使用此地址通知发送者，因为他无法知道收件人是否被邮件服务器重写。它应该采用 RFC3461 所需的格式，即 xtext 编码。

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

从服务器请求帮助文本。返回文本或在失败时返回 undef。

quit()

向远程 SMTP 服务器发送 QUIT 命令并关闭套接字连接。

can_inet6()

返回我们是否可以使用 IPv6。

can_ssl()

返回我们是否可以使用 SSL。

地址

Net::SMTP 尝试使用传递的地址进行 DWIM。例如，应用程序可能会从电子邮件中提取 From: 行并将其传递给 mail()。虽然这可能有效，但不建议这样做。应用程序实际上应该使用 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 <[email protected]>。

Steve Hay <[email protected]> 从 1.22_02 版本开始维护 libnet。

版权

版权所有 (C) 1995-2004 Graham Barr。保留所有权利。

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

许可证

此模块是免费软件；您可以根据与 Perl 本身相同的条款重新分发和/或修改它，即根据 GNU 通用公共许可证或 Artistic 许可证的条款，如 LICENCE 文件中所述。

版本

版本 3.15

日期

2023 年 3 月 20 日

历史

参见 Changes 文件。