Sending Emails

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:

$mail = new Nette\Mail\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 an email written in HTML is passed using the setHtmlBody() method:

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

You don't have to create a text alternative, Nette will generate it automatically for you. And if the email does not have a subject set, it will be taken from the <title> element.

Images can also be extremely easily inserted into the HTML body of an email. Just pass the path where the images are physically located as the second parameter, and Nette will automatically include them in the email:

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

The image embedding algorithm supports the following patterns: <img src=...>, <body background=...>, url(...) inside the HTML attribute style and special syntax [[...]].

Can sending emails be even easier?

Emails are like postcards. Never send passwords or other credentials via email.

Attachments

You can, of course, attach attachments to email. Use the 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!');

Templates

If you send HTML emails, it's a great idea to write them in the Latte template system. How to do it?

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

$mail = new Nette\Mail\Message;
$mail->setFrom('John <john@example.com>')
	->addTo('jack@example.com')
	->setHtmlBody(
		$latte->renderToString('/path/to/email.latte', $params),
		'/path/to/images'
	);

File 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 automatically inserts all images, sets the subject according to the <title> element, and generates text alternative for HTML body.

Using in Nette Application

If you use e-mails together with Nette Application, ie presenters, you may want to create links in templates using the n:href attribute or the {link} tag. Latte basically does not know them, but it's very easy to add them. Creating links can do object Nette\Application\LinkGenerator, which you get by passing it using dependency injection.

use Nette;

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

	/** @var Nette\Application\UI\ITemplateFactory */
	private $templateFactory;

	public function __construct(
		Nette\Application\LinkGenerator $linkGenerator,
		Nette\Application\UI\ITemplateFactory $templateFactory
	)
	{
		$this->linkGenerator = $linkGenerator;
		$this->templateFactory = $templateFactory;
	}

	private function createTemplate()
	{
		$template = $this->templateFactory->createTemplate();
		$template->getLatte()->addProvider('uiControl', $this->linkGenerator);
		return $template;
	}

	public function createEmail()
	{
		$template = $this->createTemplate();
		$html = $template->renderToString('/path/to/email.latte', $params);

		$mail = new Nette\Mail\Message;
		$mail->setHtmlBody($html);
		// ...
		return $mail;
	}
}

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 emails. It implements the Nette\Mail\IMailer interface and several ready-made mailers are available which we will introduce.

The framework automatically adds a Nette\Mail\IMailer service based on configuration to the DI container, which you get by passing it using dependency injection.

SendmailMailer

The default mailer is SendmailMailer which uses PHP function mail. Example of use:

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

If you want to set returnPath and the server still overwrites it, use $mailer->commandArgs = '-fmy@email.com'.

SmtpMailer

To send mail via the SMTP server, use SmtpMailer.

$mailer = new Nette\Mail\SmtpMailer([
	'host' => 'smtp.gmail.com',
	'username' => 'franta@gmail.com',
	'password' => '*****',
	'secure' => 'ssl',
]);
$mailer->send($mail);

If you do not specify host, the value from php.ini will be used. The following additional keys can be used in the options:

port – if not set, the default 25 or 465 for ssl will be used
context – allows you to set SSL context options for connection
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 milliseconds.

Configuring

Overview of configuration options for the Nette Mail.

By default, the mailer Nette\Mail\SendmailMailer is used to send emails, which is not further configured. However, we can switch it to Nette\Mail\SmtpMailer:

mail:
	# use SmtpMailer
	smtp: true       # (bool) defaults to false

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (string)
	timeout: ...     # (int)
	secure: ...      # (ssl|tls|null) defaults to null
	clientHost: ...  # (string) defaults to $_SERVER['HTTP_HOST']
	persistent: ...  # (bool) defaults to false

	# context for connecting to the SMTP server, see stream_context_create()
	context:         # (array) defaults to stream_context_get_default()