Mail

Sending
E-mails

Nette Mail

Are you planning to send emails, such as newsletters or order confirmations? Nette Framework provides the necessary tools with a very user-friendly API. We will show you:

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

Installation

Download and install the library using Composer:

composer require nette/mail

Creating Emails

An email is a Nette\Mail\Message object. Let's create one like this:

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

All specified parameters must be in UTF-8 encoding.

In addition to specifying recipients with addTo(), you can also specify recipients for a copy with addCc(), or recipients for a blind copy with addBcc(). All these methods, including setFrom(), accept the 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 need to create a text alternative; Nette will generate it automatically for you. And if the email doesn't have a subject set, it will try to take it from the <title> element.

Images can also be embedded into the HTML body exceptionally easily. 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 searches for these patterns: <img src=...>, <body background=...>, url(...) inside the HTML style attribute, and the special syntax [[...]].

Could sending emails be even easier?

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

Attachments

You can, of course, attach files to emails. Use the addAttachment(string $file, ?string $content = null, ?string $contentType = null) method for this.

// attaches the file /path/to/example.zip to the email with the name example.zip
$mail->addAttachment('/path/to/example.zip');

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

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

Templates

If you send HTML emails, writing them in the Latte templating system is a great option. 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 embeds all images, sets the subject based on the <title> element, and generates a text alternative for the HTML.

Usage in Nette Application

If you use emails together with Nette Application, i.e., with presenters, you might want to create links in templates using the n:href attribute or the {link} tag. Latte doesn't know these by default, but it's very easy to add them. The Nette\Application\LinkGenerator object can create links, and you can get it by passing it using dependency injection:

use Nette;

class MailSender
{
	public function __construct(
		private Nette\Application\LinkGenerator $linkGenerator,
		private Nette\Bridges\ApplicationLatte\TemplateFactory $templateFactory,
	) {
	}

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

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

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

In the template, you then create links as you are used to. All links created via LinkGenerator will be absolute.

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

CSS Inlining

Nette\Mail\CssInliner converts CSS rules into inline style attributes so that emails render consistently across all clients. It also generates HTML attributes for Outlook compatibility.

Requires PHP 8.4 or later and the dom extension.

Most email clients have limited support for <style> tags or ignore them entirely. To ensure correct rendering, CSS rules need to be converted to inline style attributes on individual elements. Simply pass your HTML through inline():

$inliner = new Nette\Mail\CssInliner;
$html = $inliner->inline($html);

For example, if the HTML contains:

<style>
p { margin: 0; color: #333; }
a { color: #a0704e; }
</style>
<p>Hello <a href="#">world</a></p>

The result after inlining will be (the <style> tag is preserved but omitted here for brevity):

<p style="margin: 0; color: #333">Hello <a href="#" style="color: #a0704e">world</a></p>

The <style> tag is always preserved in the output, so @media queries and other rules that cannot be inlined keep working.

In addition to extracting styles from <style> tags, you can also provide CSS via the addCss() method. You need to inline CSS before passing the HTML to setHtmlBody():

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

$html = $latte->renderToString('/path/to/email.latte', $params);
$html = (new Nette\Mail\CssInliner)
	->addCss(file_get_contents('/path/to/email.css'))
	->inline($html);

$mail = new Nette\Mail\Message;
$mail->setHtmlBody($html);

When the same CSS property is set by multiple sources, later sources override earlier ones. Rules from <style> tags have the lowest priority, followed by rules added via addCss(). If an element already has an inline style attribute in the HTML, it always takes the highest precedence.

At-rules like @media or @font-face are skipped during inlining. Note that pseudo-classes like :hover cannot be meaningfully inlined, since inline styles do not support dynamic states.

HTML Attributes for Outlook

Desktop versions of Microsoft Outlook use the Word rendering engine, which doesn't understand many CSS properties. To ensure compatibility, CssInliner automatically generates corresponding HTML attributes from CSS rules alongside inline styles:

CSS Property HTML Attribute Applied To
background-color bgcolor <table>, <td>, <th>, <body>, <tr>
width width <table>, <td>, <th>, <img>
height height <table>, <td>, <th>, <img>
border-spacing cellspacing <table>

For width, height, and cellspacing, the px unit is automatically stripped (e.g., width: 600px becomes width="600"). Both the inline style and the HTML attribute are always set, so the email renders correctly in modern clients and Outlook alike.

HTML attributes are generated only from CSS rules processed by CssInliner, not from style attributes already present in the original HTML.

Sending Emails

Mailer is a class responsible for sending emails. It implements the Nette\Mail\Mailer interface, and several pre-made mailers are available, which we will introduce.

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

SendmailMailer

The default mailer is SendmailMailer, which uses the PHP function mail. Example usage:

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

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

SmtpMailer

To send mail via an SMTP server, use SmtpMailer.

$mailer = new Nette\Mail\SmtpMailer(
	host: 'smtp.gmail.com',
	username: 'john@gmail.com',
	password: '*****', // your password
	encryption: 'ssl', // or 'tls'
);
$mailer->send($mail);

The following additional parameters can be passed to the constructor:

  • port – if not set, the default 25 or 465 for ssl (or 587 for tls) will be used
  • timeout – timeout for the SMTP connection
  • persistent – use a persistent connection
  • clientHost – specify the client's host header
  • streamOptions – allows setting SSL context options for the connection

FallbackMailer

This mailer does not send emails directly but mediates sending through a set of mailers. If one mailer fails, it retries with 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 retries and the waiting time in milliseconds.

DKIM

DKIM (DomainKeys Identified Mail) is a technology for increasing email trustworthiness, which also helps detect spoofed messages. The sent message is signed 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. If the signature matches, it proves that the email actually originated from the sender's domain and that the message was not modified during transmission.

You can set up the mailer to sign emails directly in the configuration. If you do not use dependency injection, it is used as follows:

$signer = new Nette\Mail\DkimSigner(
	domain: 'yourdomain.com',
	selector: 'dkim', // selector from DNS record
	privateKey: file_get_contents('/path/to/dkim.key'), // path to your private key
	passPhrase: 'your_passphrase', // passphrase for the private key, if any
);

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

Configuration

Overview of configuration options for Nette Mail. If you are not using the entire framework but only this library, read how to load the configuration.

By default, the Nette\Mail\SendmailMailer is used for sending emails, which requires no further configuration. However, we can switch it to Nette\Mail\SmtpMailer:

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

	host: ...        # (string) SMTP server hostname
	port: ...        # (int) SMTP server port
	username: ...    # (string) username for SMTP authentication
	password: ...    # (string) password for SMTP authentication
	timeout: ...     # (int) timeout for SMTP connection
	encryption: ...  # (ssl|tls|null) defaults to null (alias 'secure' means 'ssl')
	clientHost: ...  # (string) client hostname, defaults to $_SERVER['HTTP_HOST'] or 'localhost'
	persistent: ...  # (bool) use persistent connection, defaults to false

	# stream context options for the SMTP connection, defaults to stream_context_get_default()
	context:
		ssl:         # all options at https://www.php.net/manual/en/context.ssl.php
			allow_self_signed: ...
			...
		http:        # options list at https://www.php.net/manual/en/context.http.php
			header: ...
			...

You can disable SSL certificate verification using the context › ssl › verify_peer: false option. We strongly recommend against doing this as it makes the application vulnerable. Instead, add certificates to the trust store.

To increase trustworthiness, we can sign emails using DKIM technology:

mail:
	dkim:
		domain: myweb.com                  # your domain
		selector: lovenette                # DKIM selector
		privateKey: %appDir%/cert/dkim.key # path to your private key file
		passPhrase: ...                    # passphrase for the private key, if needed

DI Services

These services are added to the DI container:

Name Type Description
mail.mailer Nette\Mail\Mailer email sending class
mail.signer Nette\Mail\Signer DKIM signing
  1. Documentation
  2. Nette Mail
version: 4.0 3.x 2.x
Image