Шаблоны
От Сергей and Виктория
От Сергей and Виктория
Шаблоны писем: создание, переменные, псевдонимы, проверка перед отправкой и перенос между серверами.
Использование шаблонов в Haskimail
Шаблоны позволяют один раз сверстать общие части писем — стили CSS, шапку и подвал — и использовать их во всех письмах. Без шаблонов общий код приходится поддерживать в каждом письме отдельно. С шаблонами счета, приветственные письма и письма для сброса пароля используют общие элементы, а в коде вашего приложения остаётся только содержание конкретного письма. Добавление шаблона Для быстрого старта в Haskimail есть готовые стартовые шаблоны. Можно создать и свой шаблон с нуля. 1. Откройте нужный сервер и перейдите в раздел Шаблоны. 2. Нажмите Добавить шаблон. Кнопка «Добавить шаблон» на вкладке «Шаблоны» сервера 3. Haskimail покажет стартовые шаблоны. Для примера выберем «Добро пожаловать!». Выбор стартового шаблона: «Добро пожаловать!» Редактирование шаблонов Чтобы изменить шаблон, откройте его из списка на вкладке Шаблоны. Во встроенном редакторе можно поправить HTML, CSS и текстовую версию, а результат посмотреть на вкладке Предпросмотр. Подробнее о редакторе — в статье «Стартовый шаблон». В стартовых шаблонах стили CSS собраны в блоке <style> в заголовке письма. Многие почтовые клиенты лучше понимают стили, встроенные прямо в теги, поэтому при отправке Haskimail автоматически переносит стили в разметку. Так шаблон удобно редактировать, а письмо корректно отображается у получателей. Переменные в шаблоне Чтобы подставить в письмо имя клиента, номер заказа или другие данные, добавьте в тему, HTML и текстовую версию шаблона переменные в двойных фигурных скобках, например {{name}} или {{order}}. При отправке передайте значения в поле TemplateModel. Ключ — это переменная вместе со скобками: {"{{name}}": "Иван", "{{order}}": "1042"}. Переменные {{SENDDATE}} и %SENDDATE% заменяются датой отправки автоматически. Текстовая версия шаблона Письмо по шаблону содержит две части: HTML и текстовую версию из шаблона. Текстовую версию показывают почтовые клиенты без поддержки HTML, умные часы и программы для чтения с экрана, а письмо с обеими частями лучше доставляется. Заполняйте её тем же содержанием, что и HTML, без вёрстки, и с теми же переменными. Если копируете текст из HTML, проверьте, что в нём не остались теги вроде <p> и </p> — получатели увидят их как есть. Убедиться, что текстовая версия дошла, можно в исходнике письма: там будут части text/plain и text/html. Проверка шаблона Перед отправкой шаблон можно проверить: API покажет, что получит получатель, и найдёт переменные без значения. Для этого используйте метод POST /templates/validate. Подробнее — в статье «Проверка шаблона перед отправкой».
Стартовый шаблон
В Haskimail есть готовые шаблоны для частых транзакционных писем: приветствия, уведомления о комментариях, сброса пароля, квитанций и счетов, окончания пробного периода, приглашения пользователей и других. Любой шаблон можно доработать под себя во встроенном редакторе. Письма по шаблонам отправляются через API — методами /email/withTemplate и /email/batchWithTemplates. Как добавить стартовый шаблон Откройте нужный сервер и перейдите в раздел Шаблоны. Нажмите Добавить шаблон и выберите подходящий стартовый шаблон. Страница «Выбрать шаблон» со стартовыми шаблонами Редактирование шаблона Чтобы изменить шаблон, откройте вкладку Редактировать. Здесь редактируются HTML- и текстовая версии письма. Посмотреть, как выглядит письмо, можно на вкладке Предпросмотр. Редактор шаблона: вкладка «Редактировать», переключатель HTML и «Текст» Стили CSS в стартовых шаблонах собраны в блоке <style> в заголовке письма. При отправке Haskimail автоматически переносит их в разметку, потому что многие почтовые клиенты лучше понимают встроенные стили. Так шаблон удобно редактировать, а письмо корректно отображается у получателей. Отправка тестового письма Когда шаблон готов, проверьте, как он выглядит в настоящем почтовом клиенте. Нажмите Отправить тест — письмо с тестовыми значениями переменных придёт на указанный адрес. Тестовые письма входят в месячный лимит писем вашего тарифа. Кнопка «Отправить тест» в редакторе шаблона Окно «Отправить тестовое письмо»: адрес получателя и обратный адрес Чтобы посмотреть письмо сразу во многих почтовых клиентах, используйте сервисы вроде Litmus или Email on Acid. Стартовые шаблоны уже проверены, но после любых изменений обязательно отправьте тестовое письмо.
Псевдоним шаблона
У каждого шаблона в Haskimail есть псевдоним (алиас). По нему удобно ссылаться на шаблон при отправке вместо числового ID: псевдоним понятнее и его проще использовать в коде. Задать псевдоним можно в интерфейсе или через API шаблонов. Установка псевдонима через интерфейс Haskimail 1. Откройте шаблон. 2. Нажмите на текущий псевдоним. 3. Введите новый псевдоним, например welcome_new. Важно: если вы меняете псевдоним, обновите его и в коде приложения, которое отправляет письма с этим шаблоном. Установка псевдонима через API шаблонов Чтобы задать псевдоним, отправьте запрос PUT https://api.haskimail.ru/templates/{templateIdOrAlias} с серверным ключом в заголовке X-Haskimail-Server-Token. Метод перезаписывает шаблон целиком, поэтому передайте все поля шаблона — Name, Subject, HtmlBody, TextBody — и новый Alias. Пропущенные поля станут пустыми. Пример: { "Name": "Приветствие", "Alias": "my-alias", "Subject": "Добро пожаловать, {{name}}!", "HtmlBody": "<p>Здравствуйте, {{name}}!</p>", "TextBody": "Здравствуйте, {{name}}!" } Теперь при отправке письма можно указывать псевдоним в поле TemplateAlias вместо TemplateId. Ключи в TemplateModel — это переменные вместе с фигурными скобками. Пример: { "TemplateAlias": "my-alias", "TemplateModel": { "{{name}}": "Иван" }, "From": "sender@example.com", "To": "receiver@example.com" }
Проверка шаблона перед отправкой
Метод POST /templates/validate показывает, что получит получатель письма по шаблону, и находит фрагменты {{…}}, для которых в модели нет значения. Метод ничего не сохраняет и не отправляет, поэтому его можно вызывать сколько угодно раз. Когда это пригодится - Перед первой отправкой нового шаблона. - После правки шаблона, чтобы убедиться, что ничего не сломалось. - Когда получатели видят в письме текст вида {{name}} вместо имени. - В автоматических тестах вашего приложения: проверяйте шаблоны до выкладки. Как проверить шаблон 1. Передайте в запросе тему (Subject), HTML (HtmlBody) и текстовую версию (TextBody) шаблона. Нужна хотя бы одна из трёх частей. 2. Добавьте тестовые подстановки в поле TestRenderModel — те же, что вы передаёте в TemplateModel при отправке. 3. Изучите ответ: готовое письмо и список найденных ошибок. Подстановка буквальная: ключ модели — это фрагмент текста шаблона вместе со скобками, значение — строка или число. Например, {"{{name}}": "Иван"} заменит {{name}} на «Иван». Фрагменты {{SENDDATE}} и %SENDDATE% заменяются сегодняшней датой, их передавать не нужно. Пример запроса cURL: curl "https://api.haskimail.ru/templates/validate" \ -X POST \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Haskimail-Server-Token: ваш_токен_сервера" \ -d '{ "Subject": "Заказ {{order}} оформлен", "HtmlBody": "<p>Здравствуйте, {{name}}!</p>\n<p>Трек-номер: {{track}}</p>", "TextBody": "Здравствуйте, {{name}}! Заказ {{order}} оформлен.", "TestRenderModel": { "{{name}}": "Иван", "{{order}}": "1042" } }' В этом примере в модели нет значения для {{track}}. Что вернёт API API отвечает HTTP 200, даже если в шаблоне есть ошибки. Общий результат — в поле AllContentIsValid: true, если ошибок нет ни в одной из переданных частей. Для каждой переданной части — Subject, HtmlBody, TextBody — ответ содержит: - RenderedContent — часть письма после подстановки, как её получит получатель; - ContentIsValid — true, если в этой части нет ошибок; - ValidationErrors — список ошибок. У каждой есть описание (Message), номер строки (Line) и позиция в строке (CharacterPosition) в исходном тексте этой части, считая с 1. Ещё в ответе есть SuggestedTemplateModel — готовая модель со всеми фрагментами {{…}} из шаблона. Если значения для фрагмента нет, вместо него стоит заглушка, например track_Value. Её удобно скопировать и дополнить. Ответ на пример выше: { "AllContentIsValid": false, "Subject": { "ContentIsValid": true, "ValidationErrors": [], "RenderedContent": "Заказ 1042 оформлен" }, "HtmlBody": { "ContentIsValid": false, "ValidationErrors": [ { "Message": "Нет значения для {{track}}: в TestRenderModel нет такого ключа", "Line": 2, "CharacterPosition": 16 } ], "RenderedContent": "<p>Здравствуйте, Иван!</p>\n<p>Трек-номер: {{track}}</p>" }, "TextBody": { "ContentIsValid": true, "ValidationErrors": [], "RenderedContent": "Здравствуйте, Иван! Заказ 1042 оформлен." }, "SuggestedTemplateModel": { "{{order}}": "1042", "{{name}}": "Иван", "{{track}}": "track_Value" } } Что считается ошибкой - Фрагмент {{…}}, оставшийся после подстановки: в модели нет такого ключа или он записан иначе, например с пробелами внутри скобок. - Открывающие скобки {{ без закрывающих }}. Больше ничего не проверяется: разметка HTML не валидируется, ссылки и открытия при проверке не отслеживаются. Важно: если в ошибке Line и CharacterPosition равны 0, фрагмент {{…}} появился из значения модели, а в самом шаблоне его нет. Проверьте значения в TestRenderModel. Если проверять нечего или TestRenderModel передан не как объект «фрагмент → значение», API вернёт HTTP 422 с кодом 1120. Частые вопросы Сохраняется ли шаблон при проверке? Нет. Метод только показывает результат. Чтобы сохранить шаблон, создайте или обновите его в разделе «Шаблоны» или через API шаблонов. Уходит ли письмо получателю? Нет, проверка не отправляет писем. Какой ключ нужен? Серверный ключ в заголовке X-Haskimail-Server-Token или ключ аккаунта в заголовке X-Haskimail-Account-Token. Можно ли проверить уже сохранённый шаблон? Да. Получите его тему, HTML и текстовую версию методом GET /templates/{templateIdOrAlias} и передайте их в запросе проверки вместе с тестовой моделью. Можно ли проверить шаблон с тестовым ключом? Нет. HASKIMAIL_API_TEST работает только с методами отправки, а на проверку шаблона с ним API ответит HTTP 401 с кодом 10. Подробнее — в API шаблонов и в статье «Использование шаблонов в Haskimail».
Как перенести шаблоны на другой сервер
В Haskimail шаблоны можно переносить между серверами двумя способами: скопировать один шаблон в интерфейсе или перенести все шаблоны сервера через API. Копирование одного шаблона 1. Откройте вкладку Шаблоны на нужном сервере. 2. В меню рядом с шаблоном выберите Копировать. Меню шаблона на вкладке «Шаблоны»: пункт «Копировать» 3. Введите название шаблона, выберите сервер, на который его нужно скопировать, и нажмите Копировать. 4. После копирования можно сразу отредактировать копию или вернуться к исходному шаблону. Окно «Копировать шаблон»: название копии и выбор SMTP-сервера Исходный шаблон при этом остаётся на месте. Перенос всех шаблонов через API Метод PUT /templates/push переносит все шаблоны с одного сервера на другой. Он пригодится, например, чтобы перенести шаблоны из тестового окружения в рабочее. Важно: шаблоны именно переносятся, а не копируются — на исходном сервере их не останется. Если нужно сохранить их и там, используйте копирование в интерфейсе. Для запроса нужен API-ключ аккаунта. Параметры: - SourceServerID — ID сервера, с которого переносятся шаблоны; - DestinationServerID — ID сервера, на который они переносятся; - PerformChanges — true, чтобы выполнить перенос, или false, чтобы только посмотреть, какие шаблоны будут перенесены. Сначала рекомендуем выполнить запрос с "PerformChanges": false и проверить список. curl "https://api.haskimail.ru/templates/push" \ -X PUT \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Haskimail-Account-Token: ваш_ключ_аккаунта" \ -d '{ "SourceServerID": 12345, "DestinationServerID": 67890, "PerformChanges": true }' Псевдонимы шаблонов на целевом сервере должны быть уникальными. Например, шаблон с псевдонимом welcome-email нельзя перенести на сервер, где уже есть шаблон с таким же псевдонимом. Подробнее — в документации по шаблонам.
Часто задаваемые вопросы по шаблонам
Как скопировать шаблон на другой сервер? Один шаблон можно скопировать в интерфейсе: на вкладке Шаблоны откройте меню рядом с шаблоном, выберите Копировать и укажите сервер. Меню шаблона на вкладке «Шаблоны»: пункт «Копировать» Все шаблоны сервера можно перенести через API методом PUT /templates/push. Учтите, что этот метод переносит шаблоны, а не копирует: на исходном сервере их не останется. Подробнее — в статье «Как перенести шаблоны на другой сервер». Сколько шаблонов можно создать на сервере? До 100 шаблонов на одном сервере. Как добавить ссылку для отписки в шаблон? В письмах из каналов массовых рассылок ссылка для отписки обязательна. Добавьте в HTML шаблона плейсхолдер %ОТПИСАТЬСЯ% в адрес ссылки: <a class="unsub_link" href="%ОТПИСАТЬСЯ%">Отписаться</a> В транзакционных письмах ссылка отписки тоже работает, но там она необязательна. Подробнее — в статье «Ссылка отписки». Как задать тему письма при отправке по шаблону? По умолчанию тема берётся из шаблона. Её можно заменить для конкретного письма полем Subject в запросе — тогда тема шаблона не используется. Но обычно удобнее оставить тему в шаблоне и менять её переменными. Например, если тема шаблона — {{name}}, ваш заказ {{order}} отправлен, а в запросе передано: "TemplateModel": { "{{name}}": "Иван", "{{order}}": "1042" } то получатель увидит тему «Иван, ваш заказ 1042 отправлен». Ошибка 1122 Проверьте, нет ли в <head> HTML-шаблона тега <link>. Такие теги не поддерживаются и вызывают эту ошибку. Подключайте стили через блок <style>. Можно ли отправить несколько писем по шаблону одним запросом? Да, через метод /email/batchWithTemplates — до 500 писем за запрос. Подробнее — в статье «Пакетная отправка писем через API». Как проверить шаблон перед отправкой? Используйте метод POST /templates/validate: он покажет, как будет выглядеть письмо, и найдёт переменные без значения, ничего не отправляя. Подробнее — в статье «Проверка шаблона перед отправкой». Работает ли тестовый ключ HASKIMAIL_API_TEST с шаблонами? Да, тестовый ключ работает со всеми методами отправки, в том числе /email/withTemplate и /email/batchWithTemplates: API проверит запрос, но письмо не создаст. Он проверяет только сам запрос, а не настройки сервера. Чтобы проверить отправку по шаблонам целиком, используйте сервер «Песочница».