README

简介

您是否要发送如时事通讯或订单确认之类的电子邮件？Nette 框架提供了一个非常棒的API，提供了必要的工具。

文档可以在网站上找到。

支持我

您喜欢Nette Mail吗？您是否期待新功能的出现？

谢谢！

安装

composer require nette/mail

它需要PHP版本8.0，并支持PHP 8.4。

创建电子邮件

电子邮件是一个 Nette\Mail\Message 对象。

$mail = new Nette\Mail\Message;
$mail->setFrom('John <[email protected]>')
	->addTo('[email protected]')
	->addTo('[email protected]')
	->setSubject('Order Confirmation')
	->setBody("Hello, Your order has been accepted.");

所有参数都必须以UTF-8编码。

除了使用 addTo() 方法指定收件人外，您还可以使用 addCc() 指定抄送收件人，或使用 addBcc() 指定密件收件人。所有这些方法（包括 setFrom()），都接受以下三种地址

$mail->setFrom('[email protected]');
$mail->setFrom('[email protected]', 'John Doe');
$mail->setFrom('John Doe <[email protected]>');

使用 setHtmlBody() 方法通过HTML传递电子邮件正文。

$mail->setHtmlBody('<p>Hello,</p><p>Your order has been accepted.</p>');

您不需要创建文本替代版本，Nette 会自动为您生成。如果电子邮件没有设置主题，它将从 <title> 元素中获取。

也可以非常容易地将图片插入到电子邮件的HTML正文中。只需将图片实际位置的路径作为第二个参数传递，Nette 就会自动将其包含在电子邮件中。

// automatically adds /path/to/images/background.gif to the email
$mail->setHtmlBody(
	'<b>Hello</b> <img src="background.gif">',
	'/path/to/images',
);

图像嵌入算法支持以下模式： <img src=...>、<body background=...>、HTML属性 style 中的 url(...) 和特殊语法 [[...]]。

发送电子邮件还能更简单吗？

电子邮件就像明信片。永远不要通过电子邮件发送密码或其他凭证。

附件

当然，您可以将附件附加到电子邮件中。使用 addAttachment(string $file, string $content = null, string $contentType = null)。

// inserts the file /path/to/example.zip into the email under the name example.zip
$mail->addAttachment('/path/to/example.zip');

// inserts the file /path/to/example.zip into the email under the name info.zip
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));

// attaches new example.txt file contents "Hello John!"
$mail->addAttachment('example.txt', 'Hello John!');

模板

如果您要发送HTML电子邮件，最好在 Latte 模板系统中编写它们。如何做？

$latte = new Latte\Engine;
$params = [
	'orderId' => 123,
];

$mail = new Nette\Mail\Message;
$mail->setFrom('John <[email protected]>')
	->addTo('[email protected]')
	->setHtmlBody(
		$latte->renderToString('/path/to/email.latte', $params),
		'/path/to/images',
	);

文件 email.latte

<html>
<head>
	<meta charset="utf-8">
	<title>Order Confirmation</title>
	<style>
	body {
		background: url("background.png")
	}
	</style>
</head>
<body>
	<p>Hello,</p>

	<p>Your order number {$orderId} has been accepted.</p>
</body>
</html>

Nette 会自动插入所有图片，根据 <title> 元素设置主题，并生成HTML正文的文本替代版本。

发送电子邮件

Mailer 是一个负责发送电子邮件的类。它实现了 Nette\Mail\Mailer 接口，并提供了几个现成的Mailer，我们将介绍这些Mailer。

SendmailMailer

默认的Mailer是 SendmailMailer，它使用PHP函数 mail()。用法示例

$mailer = new Nette\Mail\SendmailMailer;
$mailer->send($mail);

如果您想设置 returnPath，但服务器仍然覆盖它，请使用 $mailer->commandArgs = '[email protected]'。

SmtpMailer

要通过SMTP服务器发送邮件，请使用 SmtpMailer。

$mailer = new Nette\Mail\SmtpMailer(
	host: 'smtp.gmail.com',
	username: '[email protected]',
	password: '*****',
	encryption: Nette\Mail\SmtpMailer::EncryptionSSL,
);
$mailer->send($mail);

可以将以下附加参数传递给构造函数

port - 如果未设置，则使用默认值 25 或 ssl 的 465
timeout - SMTP连接超时
persistent - 使用持久连接
clientHost - 客户端指定
streamOptions - 允许您为连接设置 SSL上下文选项

FallbackMailer

它不发送电子邮件，而是通过一系列邮件发送器发送。如果一个邮件发送器失败，它会在下一个重新尝试。如果最后一个失败，它将从第一个重新开始。

$mailer = new Nette\Mail\FallbackMailer([
	$smtpMailer,
	$backupSmtpMailer,
	$sendmailMailer,
]);
$mailer->send($mail);

构造函数中的其他参数包括重复次数和等待时间（以毫秒为单位）。

DKIM

DKIM（域密钥识别邮件）是一种值得信赖的电子邮件技术，它还有助于检测伪造的消息。发送的消息使用发送者域的私钥进行签名，并且此签名存储在电子邮件标题中。接收者服务器将此签名与存储在域DNS记录中的公钥进行比较。通过匹配签名，可以证明电子邮件确实来自发送者域，并且在消息传输过程中该消息没有被修改。

$signer = new Nette\Mail\DkimSigner(
	domain: 'nette.org',
	selector: 'dkim',
	privateKey: file_get_contents('../dkim/dkim.key'),
	passPhrase: '****',
);

$mailer = new Nette\Mail\SendmailMailer; // or SmtpMailer
$mailer->setSigner($signer);
$mailer->send($mail);

nette / mail

维护者

详细信息