Mail

Sending
E-mails

Sending E-mails

Are you going to send emails such as newsletters or order confirmations? Nette Framework provides the necessary tools with a very nice API. We will show:

  • how to create an email, including attachments
  • how to send it
  • how to combine emails and templates

Installation:

composer require nette/mail

Creating Emails

Email is a Nette\Mail\Message object:

use Nette\Mail\Message;

$mail = new Message;
$mail->setFrom('John <john@example.com>')
	->addTo('peter@example.com')
	->addTo('jack@example.com')
	->setSubject('Order Confirmation')
	->setBody("Hello, Your order has been accepted.");

All parameters must be encoded in UTF-8.

In addition to specifying recipients with the addTo() method, you can also specify the recipient of copy with addCc(), or the recipient of blind copy with addBcc(). All these methods, including setFrom(), accepts addressee in three ways:

$mail->setFrom('john.doe@example.com');
$mail->setFrom('john.doe@example.com', 'John Doe');
$mail->setFrom('John Doe <john.doe@example.com>');

The body of the email in HTML is set by the setHtmlBody() method:

$mail->setHtmlBody('<b>Sample HTML</b> <img src="background.gif">');

If an HTML e-mail has no plain-text alternative, it will be automatically generated. And if it has no subject set, it will be taken from the <title> element.

Embedded Images

Embedded images can be inserted into an email using the $mail->addEmbeddedFile('background.gif') method, but this is not necessary. Why? Because the Nette Framework finds and inserts all files referenced in the HTML code automatically. This behavior can be turned off by specifying false as the second parameter of the setHtmlBody() method, in this parameter it is also possible to pass the absolute path to the image folder.

Attachments

Adding attachments to the e-mail is simple. In order to attach a file, we use addAttachment() method:

// attaches example.zip to the e-mail
$mail->addAttachment('path/to/example.zip');

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

// attaches example.zip renamed to info.zip
$mail->addAttachment('info.zip', file_get_contents('path/to/example.zip'));

Can be sending e-mails even easier?

Templates

The real power comes in combination with Latte templating system:

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

$mail = new Message;
$mail->setFrom('John <john@example.com>')
	->addTo('jack@example.com')
	->setHtmlBody($latte->renderToString('email.latte', $params));

File email.latte:

<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; 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>

Using in Nette Application

Latte template system at its base does not know the {link} macro or the n:href attribute (and some others, such as the filter translate). These are supplemented by the TemplateFactory class from the nette/application package in conjunction with the presenter. To be able to create links in the template email, let the TemplateFactory to create a template. A presenter we will replace with LinkGenerator object, which can create links. We pass both objects through the constructor and create a template in the createTemplate () method:

class MailSender
{
	/** @var Nette\Application\LinkGenerator */
	private $linkGenerator;

	/** @var Nette\Bridges\ApplicationLatte\TemplateFactory */
	private $templateFactory;

	public function sendEmail(): void
	{
		$template = $this->createTemplate();

		$template->name = $order->getName();
		$template->setFile(__DIR__ . '/email.latte');

		$mail = new Message;
		$mail->setHtmlBody($template->renderToString());
	}

	protected function createTemplate(): Nette\Application\UI\ITemplate
	{
		$template = $this->templateFactory->createTemplate();
		$template->getLatte()->addProvider('uiControl', $this->linkGenerator);
		return $template;
	}
}

In the template, link is created like in a normal template. All links create over LinkGenerator are absolute:

<a n:href="Presenter:action">Link</a>

Sending Emails

Mailer is class responsible for sending e-mails. It implements the Nette\Mail\Mailer interface and several ready-made mailers are available.

Example of use:

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

We do not create a mailer manually in application, but we configure it and let DI container to pass object Nette\Mail\Mailer.

SendmailMailer

The default mailer is SendmailMailer which uses PHP function mail.

If you want to set returnPath and the server still overwrites it, use $commandArgs:

$mailer->commandArgs = '-fmy@email.com';

SmtpMailer

To send mail via the SMTP server, use SmtpMailer.

$mailer = new Nette\Mail\SmtpMailer([
	'host' => 'smtp.gmail.com', //  if not set, php.ini settings will be used
	'username' => 'franta@gmail.com',
	'password' => '*****',
	'secure' => 'ssl',
]);
$mailer->send($mail);

Apart from options above SmtpMailer also offers more customisation options:

  • port – If not set, will be guessed based on secure option: 465 for value ssl, 25 otherwise.
  • context – Allows to fine-grain connection according to SSL context options. Contains an array of individual options.
  • timeout – Timeout for SMTP connection
  • persistent – Use persistent connection
  • clientHost – Client designation

FallbackMailer

It does not send email but sends them through a set of mailers. If one mailer fails, it repeats the attempt at the next one. If the last one fails, it starts again from the first one.

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

Other parameters in the constructor include the number of repeat and waiting time (in miliseconds).

DKIM

DKIM (DomainKeys Identified Mail) is a trustworthy email technology that also helps detect spoofed messages. The sent message is signed by the SMTP server with the private key of the sender's domain and this signature is stored in the email header. The recipient's server compares this signature with the public key stored in the domain's DNS records. By matching the signature, it is shown that the email actually originated from the sender's domain and that the message was not modified during the transmission of the message.

$options = [
	'domain' => 'nette.org',
	'selector' => 'dkim',
	'privateKey' => file_get_contents('../dkim/dkim.key'),
	'passPhrase' => '****',
	'testMode' => true,
];

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

Related blog posts