Skip to content

Commit bf56ecf

Browse files
dgdg
committed
readme.md: updated
1 parent fa03556 commit bf56ecf

File tree

1 file changed

+154
-50
lines changed

1 file changed

+154
-50
lines changed

‎readme.md

Lines changed: 154 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -11,34 +11,23 @@ Nette Mail: Sending E-mails
1111
Introduction
1212
------------
1313

14-
Almost every web application needs to send e-mails, whether newsletters or order confirmations. This library provides necessary tools.
14+
Are you going to send emails such as newsletters or order confirmations? Nette Framework provides the necessary tools with a very nice API.
1515

16-
Documentation can be found on the [website](https://doc.nette.org/mailing).
16+
Documentation can be found on the [website](https://doc.nette.org/mailing). If you like it, **[please make a donation now](https://github.com/sponsors/dg)**. Thank you!
1717

18-
If you like Nette, **[please make a donation now](https://nette.org/donate)**. Thank you!
18+
Installation:
1919

20-
21-
Installation
22-
------------
23-
24-
The recommended way to install is via Composer:
25-
26-
```
20+
```shell
2721
composer require nette/mail
2822
```
2923

30-
It requires PHP version 7.1 and supports PHP up to 7.4.
31-
24+
Creating Emails
25+
===============
3226

33-
Usage
34-
-----
35-
36-
Example of creating an e-mail using `Nette\Mail\Message` class:
27+
Email is a [Nette\Mail\Message](https://api.nette.org/3.0/Nette/Mail/Message.html) object:
3728

3829
```php
39-
use Nette\Mail\Message;
40-
41-
$mail = new Message;
30+
$mail = new Nette\Mail\Message;
4231
$mail->setFrom('John <john@example.com>')
4332
->addTo('[email protected]')
4433
->addTo('[email protected]')
@@ -48,63 +37,178 @@ $mail->setFrom('John <[email protected]>')
4837

4938
All parameters must be encoded in UTF-8.
5039

51-
And sending:
40+
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:
5241

5342
```php
54-
use Nette\Mail\SendmailMailer;
43+
$mail->setFrom('[email protected]');
44+
$mail->setFrom('[email protected]', 'John Doe');
45+
$mail->setFrom('John Doe <john[email protected]>');
46+
```
5547

56-
$mailer = new SendmailMailer;
57-
$mailer->send($mail);
48+
The body of an email written in HTML is passed using the `setHtmlBody()` method:
49+
50+
```php
51+
$mail->setHtmlBody('<p>Hello,</p><p>Your order has been accepted.</p>');
5852
```
5953

60-
In addition to specifying recipient with `addTo()`, it's possible to specify recipient of copy with `addCc()` and recipient of blind copy: `addBcc()`.
61-
In all these methods, including `setFrom()`, we can specifiy addressee in three ways:
54+
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.
55+
56+
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:
6257

6358
```php
64-
$mail->setFrom('[email protected]');
65-
$mail->setFrom('[email protected]', 'John Doe');
66-
$mail->setFrom('John Doe <john[email protected]>');
59+
// automatically adds /path/to/images/background.gif to the email
60+
$mail->setHtmlBody(
61+
'<b>Hello</b> <img src="background.gif">',
62+
'/path/to/images'
63+
);
64+
```
65+
66+
The image embedding algorithm supports the following patterns: `<img src=...>`, `<body background=...>`, `url(...)` inside the HTML attribute `style` and special syntax `[[...]]`.
67+
68+
Can sending emails be even easier?
69+
70+
Emails are like postcards. Never send passwords or other credentials via email.
71+
72+
73+
74+
Attachments
75+
-----------
76+
77+
You can, of course, attach attachments to email. Use the `addAttachment(string $file, string $content = null, string $contentType = null)`.
78+
79+
```php
80+
// inserts the file /path/to/example.zip into the email under the name example.zip
81+
$mail->addAttachment('/path/to/example.zip');
82+
83+
// inserts the file /path/to/example.zip into the email under the name info.zip
84+
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));
85+
86+
// attaches new example.txt file contents "Hello John!"
87+
$mail->addAttachment('example.txt', 'Hello John!');
6788
```
6889

69-
HTML content can be defined using `setHtmlBody()` method:
90+
91+
Templates
92+
---------
93+
94+
If you send HTML emails, it's a great idea to write them in the [Latte](https://latte.nette.org) template system. How to do it?
7095

7196
```php
72-
$mail->setHTMLBody('<b>Sample HTML</b> <img src="background.gif">');
97+
$latte = new Latte\Engine;
98+
$params = [
99+
'orderId' => 123,
100+
];
101+
102+
$mail = new Nette\Mail\Message;
103+
$mail->setFrom('John <john@example.com>')
104+
->addTo('[email protected]')
105+
->setHtmlBody(
106+
$latte->renderToString('email.latte', $params),
107+
'/path/to/images'
108+
);
109+
```
110+
111+
File `email.latte`:
112+
113+
```html
114+
<html>
115+
<head>
116+
<meta charset="utf-8">
117+
<title>Order Confirmation</title>
118+
<style>
119+
body {
120+
background: url("background.png")
121+
}
122+
</style>
123+
</head>
124+
<body>
125+
<p>Hello,</p>
126+
127+
<p>Your order number {$orderId} has been accepted.</p>
128+
</body>
129+
</html>
73130
```
74131

75-
Embedded images can be inserted using `$mail->addEmbeddedFile('background.gif')`, but it is not necessary.
76-
Why? Because Nette Framework finds and inserts all files referenced in the HTML code automatically.
77-
This behavior can be supressed by adding `false` as a second parameter of the `setHtmlBody()` method.
132+
Nette automatically inserts all images, sets the subject according to the `<title>` element, and generates text alternative for HTML body.
133+
78134

79-
If a 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.
80135

81-
Of course, it's possible to add attachments to the e-mail:
136+
Sending Emails
137+
==============
138+
139+
Mailer is class responsible for sending emails. It implements the [Nette\Mail\Mailer](https://api.nette.org/3.0/Nette/Mail/Mailer.html) interface and several ready-made mailers are available which we will introduce.
140+
141+
142+
143+
SendmailMailer
144+
--------------
145+
146+
The default mailer is SendmailMailer which uses PHP function `mail()`. Example of use:
82147

83148
```php
84-
$mail->addAttachment('example.zip');
149+
$mailer = new Nette\Mail\SendmailMailer;
150+
$mailer->send($mail);
85151
```
86152

87-
Can e-mail sending be even easier?
153+
If you want to set `returnPath` and the server still overwrites it, use `$mailer->commandArgs = '[email protected]'`.
88154

89155

90-
Custom mailer
91-
-------------
156+
SmtpMailer
157+
----------
92158

93-
Default mailer uses PHP function `mail`. If you need to send mail through a SMTP server, you can use `SmtpMailer`.
159+
To send mail via the SMTP server, use `SmtpMailer`.
94160

95161
```php
96162
$mailer = new Nette\Mail\SmtpMailer([
97-
'host' => 'smtp.gmail.com',
98-
'username' => '[email protected]',
99-
'password' => '*****',
100-
'secure' => 'ssl',
101-
'context' => [
102-
'ssl' => [
103-
'capath' => '/path/to/my/trusted/ca/folder',
104-
],
105-
],
163+
'host' => 'smtp.gmail.com',
164+
'username' => '[email protected]',
165+
'password' => '*****',
166+
'secure' => 'ssl',
106167
]);
107168
$mailer->send($mail);
108169
```
109170

110-
You can also create your own mailer - it's a class implementing Nette\Mail\Mailer interface.
171+
If you do not specify `host`, the value from php.ini will be used. The following additional keys can be used in the options:
172+
173+
* `port` - if not set, the default 25 or 465 for `ssl` will be used
174+
* `context` - allows you to set [SSL context options](https://www.php.net/manual/en/context.ssl.php) for connection
175+
* `timeout` - timeout for SMTP connection
176+
* `persistent` - use persistent connection
177+
* `clientHost` - client designation
178+
179+
180+
FallbackMailer
181+
--------------
182+
183+
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.
184+
185+
```php
186+
$mailer = new Nette\Mail\FallbackMailer([
187+
$smtpMailer,
188+
$backupSmtpMailer,
189+
$sendmailMailer
190+
]);
191+
$mailer->send($mail);
192+
```
193+
194+
Other parameters in the constructor include the number of repeat and waiting time in miliseconds.
195+
196+
197+
DKIM
198+
====
199+
200+
DKIM (DomainKeys Identified Mail) is a trustworthy email technology that 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.
201+
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.
202+
203+
```php
204+
$options = [
205+
'domain' => 'nette.org',
206+
'selector' => 'dkim',
207+
'privateKey' => file_get_contents('../dkim/dkim.key'),
208+
'passPhrase' => '****',
209+
];
210+
211+
$mailer = new Nette\Mail\SendmailMailer; // or SmtpMailer
212+
$mailer->setSigner(new Nette\Mail\DkimSigner($options));
213+
$mailer->send($mail);
214+
```

0 commit comments

Comments
 (0)