> For the complete documentation index, see [llms.txt](https://docs.johncms.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.johncms.com/10.0/obshie-svedeniya/shablony-elektronnykh-soobshenii-email.md).

# Шаблоны электронных сообщений (email)

Начиная с JohnCMS 9.3 в системе появилась поддержка шаблонов для email.

### Для чего это нужно?

Это нужно для того, чтобы отправлять хорошо оформленные письма, которые будут иметь дизайн такой же как и ваш сайт, а так же в таких письмах можно выделять нужную информацию в отличие от обычных текстовых сообщений.

### Как это работает?

Рассмотрим пример письма:

![Пример сообщения о регистрации](https://2779606936-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MU3Noae80124ohncEUR-625319254%2Fuploads%2Fgit-blob-0c1ae214220552cc7c371f539aed704d7a44b15a%2Fimage.png?alt=media)

В письмах как и на всем сайте есть основной шаблон, который является общим практически для всех страниц (header/footer. На скриншоте отмечен цифрами 1 и 3). Сам текст письма - это контентная область (на скриншоте отмечена цифрой 2), которая в разных письмах может выглядеть по разному.

Базовых шаблонов может быть несколько и каждый шаблон сообщения может использовать любой базовый шаблон.

Всё это позволит вам менять базовый шаблон не меняя все шаблоны писем. Например, вы можете сделать несколько шаблонов на все времена года, зимний, летний, весенний, осенний и менять их когда это необходимо. При этом вам нужно будет изменить всего 1 файл, а шаблоны писем изменять не придется вовсе.

### Где хранятся шаблоны?

Почтовые шаблоны так же как и основные шаблоны сайта хранятся в папке themes.

![](https://2779606936-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MU3Noae80124ohncEUR-625319254%2Fuploads%2Fgit-blob-7615a8bec2665c67bfd89f1355c872f6b5bc1f3a%2Fimage.png?alt=media)

Основной макет письма расположен в файле **themes/default/templates/emails/layout.twig**, а шаблоны конкретных сообщений — рядом с ним, в той же папке **themes/default/templates/emails**.

Письма пишутся на Twig, как и страницы сайта, и переопределяются так же: скопируйте нужный файл в свою тему, сохранив путь (**themes/имя\_темы/templates/emails/…**). Тогда при обновлении CMS переносить изменения не придётся.

Есть одно отличие от страниц. Письмо читают вне сайта, в почтовом клиенте, поэтому оно отрисовывается в собственном окружении: в нём нет ни данных о посетителе, ни csrf-токена, ни сборки стилей — стили лежат прямо в макете письма. Зато все адреса в письме абсолютные: функция `asset()` возвращает полный URL, а `home_url()` и `copyright()` дают адрес и название сайта.

Язык письма — это язык его получателя, он приходит в шаблон переменной `locale` и не зависит от языка того, кто вызвал отправку.

### Текстовая версия письма

Письмо, состоящее только из HTML, спам-фильтры считают массовой рассылкой, да и почтовые клиенты с текстовым режимом показать его не могут. Поэтому каждое письмо отправляется в двух версиях сразу, и текстовую стоит написать самому — рядом с шаблоном письма, с тем же именем и расширением **.txt.twig**:

```
themes/default/templates/emails/registration.twig      HTML-версия
themes/default/templates/emails/registration.txt.twig  текстовая версия
```

Текстовые шаблоны устроены так же и наследуют собственный макет **themes/default/templates/emails/layout.txt.twig**. Разметки в них нет, а ссылки пишутся полностью — в тексте это единственный способ по ним перейти. Экранирование в таких шаблонах отключено автоматически: адрес со знаком `&` попадёт в письмо как есть.

Строки в текстовой версии используются те же, что и в HTML, поэтому отдельно переводить её не нужно. Если в строке есть разметка, уберите её фильтром `striptags`:

```twig
{{ __('You have successfully registered on the <a href="%s">%s</a> website', home_url(), copyright())|striptags }}
```

Если текстового шаблона нет, текст получается автоматически из HTML. Результат заметно хуже — ссылки при этом теряются, — поэтому для писем, в которых есть кнопка или ссылка, текстовую версию лучше написать.