API шаблонов Email

API шаблонов Email управляет многоразовыми шаблонами email, которые лежат в основе пресетов email приложения — теми же шаблонами, которые вы создаете в редакторе email в Control Panel. Каждый шаблон хранит темы для разных языков, информацию об отправителе и содержимое редактора, и идентифицируется по коду пресета email, с которым он связан. Используйте этот код для отправки шаблона через Notify (полезная нагрузка email email_template) или точку Send email в Customer Journey.

Базовый URL

https://rpc-api.svc-nue.pushwoosh.com

Все эндпоинты обслуживаются по HTTPS. Запросы и ответы используют application/json, если не указано иное.

Аутентификация

Каждый запрос должен включать заголовок Authorization с вашим токеном Server API:

Authorization: Api YOUR_API_TOKEN

Соглашения

Именование полей: тела запросов и параметры query/path принимают lowerCamelCase (например, previewSettings, searchByLabel, includeHtml) — сервер разбирает любой регистр. Ответы всегда маршалируются с использованием имен полей proto в snake_case (per_page, email_template, sender_info, preview_settings и так далее). Примеры ответов и справочник объектов ниже используют этот регистр.
code: каждый ответ с шаблоном содержит код связанного с ним пресета email, а не внутренний ID шаблона. Передавайте этот же код в Get, Update, Delete и в вышеупомянутые API сообщений/journey.
Незаполненные поля: ответы включают все поля, даже если они пустые или имеют нулевое значение.

Ответы об ошибках

HTTP-статус	Значение
`400 Bad Request`	Неверный аргумент — обязательное поле отсутствует или имеет неверный формат, или не выполнено предварительное условие (например, удаление шаблона, который все еще используется в journey).
`401 Unauthorized`	Отсутствует или недействителен заголовок `Authorization`.
`403 Forbidden`	Приложение или пресет не принадлежат аккаунту вызывающей стороны.
`404 Not Found`	Шаблон, пресет или приложение не найдены.
`500 Internal Server Error`	Неожиданный сбой на стороне сервера.

Эндпоинты

Метод	Путь	Описание
`POST`	`/api/email_templates`	Создать новый шаблон email
`GET`	`/api/email_templates`	Получить список шаблонов email приложения
`GET`	`/api/email_templates/{code}`	Получить один шаблон email
`PUT`	`/api/email_templates/{code}`	Обновить шаблон email
`DELETE`	`/api/email_templates/{code}`	Удалить шаблон email
`POST`	`/api/email_templates:clone`	Клонировать шаблон email в приложение

Создание

Создает новый шаблон email — его содержимое редактора плюс связанный пресет email — в приложении и возвращает сгенерированный код шаблона.

POST /api/email_templates

Тело запроса

Параметр	Тип	Обязательный	Описание
`application`	string	Да	Код приложения Pushwoosh, в котором нужно создать шаблон.
`name`	string	Да	Название шаблона, 1–255 символов.
`content`	object	Да	Объект содержимого email.
`label`	string	Нет	Произвольная метка, до 255 символов.
`categories`	array of strings	Нет	Названия категорий для тегирования шаблона.
`previewSettings`	object	Нет	Произвольные настройки предпросмотра редактора, сохраняются и возвращаются как есть.
`system`	boolean	Нет	Помечает шаблон как системный — внутренняя функция, например, фрагмент синхронизированного блока. Системные шаблоны скрыты из `List` (см. примечание ниже), но остаются доступными по коду. По умолчанию `false`.

Пример запроса

{
  "application": "XXXXX-XXXXX",
  "name": "Welcome email",
  "label": "onboarding",
  "categories": ["lifecycle"],
  "content": {
    "senderInfo": {
      "from": { "email": "hello@acme.com", "name": "Acme" },
      "replyTo": { "email": "support@acme.com", "name": "Acme Support" }
    },
    "subject": { "en": "Welcome to Acme!", "default": "Welcome to Acme!" },
    "pushwoosh": {
      "html": "<html><body>Welcome, {name|string|there}!</body></html>",
      "localizationData": { "default": { "name": "there" } }
    }
  }
}

Ответ

Возвращает { "email_template": { ... } } — созданный объект шаблона email, но без content (этот эндпоинт не возвращает его). Вызовите Get с возвращенным code, если вам нужно прочитать содержимое.

Список

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

GET /api/email_templates

Параметры запроса

Параметр	Тип	Обязательный	Описание
`application`	string	Да	Код приложения, для которого нужно получить список шаблонов.
`orderBy`	string	Нет	`NAME` (по умолчанию), `CREATED` или `UPDATED`.
`orderDirection`	string	Нет	`ASC` (по умолчанию) или `DESC`.
`page`	integer	Нет	Индекс страницы, начиная с нуля.
`perPage`	integer	Нет	Размер страницы. По умолчанию `100`, если не указан или равен `0`. Этот эндпоинт не имеет явного максимума.
`searchByName`	string	Нет	Поиск по подстроке (`like %value%`) в названии шаблона или его коде — достаточно одного совпадения.
`searchByLabel`	string	Нет	Поиск по подстроке в метке (`like %label%`) или точное совпадение, если `strictSearchByLabel` равно `true`.
`strictSearchByLabel`	boolean	Нет	Использовать точное совпадение вместо поиска по подстроке для `searchByLabel`.
`searchByCategory`	array of strings	Нет	Повторите параметр для фильтрации по нескольким категориям, например, `?searchByCategory=lifecycle&searchByCategory=promo`.

Ответ

Поле	Тип	Описание
`email_templates`	array of objects	Текущая страница объектов шаблонов email. `content` равен `null` для каждого элемента.
`page`	integer	Возвращенный индекс страницы.
`per_page`	integer	Размер страницы, использованный для этого ответа.
`total`	integer	Общее количество шаблонов, соответствующих фильтрам, на всех страницах.

Пример ответа

{
  "email_templates": [
    { "code": "AAAAA-BBBBB", "name": "Welcome email", "label": "onboarding", "categories": ["lifecycle"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

Получение

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

GET /api/email_templates/{code}

Параметры пути

Параметр	Тип	Описание
`code`	string	Код шаблона (код связанного с ним пресета email).

Параметры запроса

Параметр	Тип	Обязательный	Описание
`includeHtml`	boolean	Нет	Возвращать ли сгенерированный `html` вместе с содержимым редактора. По умолчанию `true`. Установите в `false`, чтобы пропустить его — обычно это более половины полезной нагрузки, а содержимое редактора уже описывает шаблон.

Ответ

Возвращает { "email_template": { ... } }, полный объект шаблона email.

Обновление

Обновляет существующий шаблон email по коду, перезаписывая предоставленные поля.

PUT /api/email_templates/{code}

Параметры пути

Параметр	Тип	Описание
`code`	string	Код шаблона для обновления.

Тело запроса

Параметр	Тип	Обязательный	Описание
`name`	string	Нет	Новое название, 1–255 символов. Опустите, чтобы сохранить текущее название.
`content`	object	Нет	Новый объект содержимого email, полностью заменяющий сохраненное содержимое. Опустите, чтобы оставить содержимое без изменений.
`label`	string	Нет	Новая метка. Всегда перезаписывается — опустите или отправьте `""`, чтобы очистить ее.
`categories`	array of strings	Нет	Новый полный набор названий категорий. Опустите, чтобы оставить категории без изменений; отправьте `[]`, чтобы очистить их.
`previewSettings`	object	Нет	Новые настройки предпросмотра. Опустите, чтобы оставить без изменений.

Пример запроса

{
  "name": "Welcome email v2",
  "label": "onboarding",
  "content": {
    "senderInfo": { "from": { "email": "hello@acme.com", "name": "Acme" } },
    "subject": { "default": "Welcome to Acme — updated!" },
    "pushwoosh": {
      "html": "<html>...</html>",
      "localizationData": {}
    }
  }
}

Ответ

Возвращает { "email_template": { ... } } — обновленный объект шаблона email, также без content. Вызовите Get, если вам нужно прочитать содержимое.

Удаление

Удаляет шаблон email и связанный с ним пресет по коду, удаляя сохраненное содержимое.

DELETE /api/email_templates/{code}

Параметры пути

Параметр	Тип	Описание
`code`	string	Код шаблона для удаления.

Ответ

Пустой объект в случае успеха: {}.

Клонирование

Клонирует шаблон email — его содержимое и пресет — в целевое приложение, опционально под новым названием.

POST /api/email_templates:clone

Тело запроса

Параметр	Тип	Обязательный	Описание
`emailPresetCode`	string	Да	`code` шаблона для клонирования (возвращаемый `Create`, `Get`, `List` или `Update`). Назван `emailPresetCode`, потому что это код связанного пресета email — см. Соглашения.
`application`	string	Да	Код целевого приложения. Может быть тем же приложением или другим, принадлежащим тому же аккаунту.
`name`	string	Нет	Название для клона, 1–255 символов. По умолчанию используется название исходного шаблона.

Пример запроса

{
  "emailPresetCode": "AAAAA-BBBBB",
  "application": "YYYYY-YYYYY",
  "name": "Welcome email (copy)"
}

Ответ

Поле	Тип	Описание
`email_preset_code`	string	`code` нового шаблона — тот же идентификатор, который используется в вызовах `Get`/`Update`/`Delete` как `code`.

Справочник объектов

Имена полей ниже соответствуют тому, что фактически возвращают Get, List, Update и Create — имена полей proto в snake_case (см. Соглашения). Когда вы отправляете эти же структуры обратно в теле запроса (Create, Update), форма lowerCamelCase, используемая в примерах запросов выше, также работает; сервер принимает любой регистр на входе.

Объект шаблона email

Поле	Тип	Описание
`code`	string	Код связанного пресета email. Идентифицирует этот шаблон во всех остальных частях API.
`name`	string	Название шаблона.
`label`	string	Произвольная метка.
`categories`	array of strings	Названия категорий.
`content`	object	Объект содержимого email. Заполняется только методом `Get`; `null` в ответах `Create`, `List` и `Update`.
`preview_settings`	object	Произвольные настройки предпросмотра редактора.
`created`	string (RFC 3339)	Временная метка создания.
`updated`	string (RFC 3339)	Временная метка последнего обновления.

Объект содержимого email

Поле	Тип	Описание
`sender_info`	object	Объект информации об отправителе — адреса `from` и `reply_to`.
`subject`	object (map)	Тема для каждой локали, например, `{ "en": "Subject", "default": "Subject" }`.
`unlayer` / `pushwoosh` / `smartcards`	object	Содержимое редактора. Должно быть установлено ровно одно из этих полей — оно определяет, какой редактор создал (и будет отображать) шаблон. См. типы редакторов ниже.

Типы редакторов

Тип	Поле	Обязательные подполя	Описание
`unlayer`	`html`, `localization_data`, `editor_config`	`editor_config`, `localization_data`	Блочный редактор с перетаскиванием (Unlayer). `editor_config` — это JSON дизайна Unlayer.
`pushwoosh`	`html`, `localization_data`	`localization_data`	Собственный HTML-редактор Pushwoosh. Рекомендуется для шаблонов, создаваемых программно/через API.
`smartcards`	`html`, `localization_data`, `content`	`content`, `localization_data`	Блочный редактор Smart Cards; `content` — это его специфический JSON.

В каждом типе html — это сгенерированный результат. localization_data — это собственное содержимое редактора для каждой локали: объект, ключами которого являются коды локалей (en, es, default, …), а значениями — копия полей редактора для этой локали. Его внутренняя структура специфична для редактора и непрозрачна для этого API — API сохраняет и возвращает его как есть. Он обязателен при Create/Update для каждого типа (отправьте {}, если локализовать нечего).

Каждый раз, когда API возвращает content (в настоящее время только Get, так как Create и Update не возвращают его), он гарантирует, что одна локаль будет представлена как default: если вы сами не отправили ключ default, он повышает en (или, если его нет, первый попавшийся ключ локали) до default, переименовывая его — все остальные отправленные вами локали сохраняются как есть. subject обрабатывается так же. Это отличается от Clone, который сохраняет только это одно значение локали по умолчанию и отбрасывает остальные.

Это переименование применяется только при построении ответа, но не отменяется при записи. Если вы возьмете ответ Get как есть и отправите его прямо в Update, повышенный ключ (например, en) теперь будет буквально default, и Update сохранит именно то, что вы отправили: исходный ключ en с этого момента исчезнет навсегда. Если вам нужно сохранить исходный ключ локали, переименуйте default обратно в него самостоятельно перед вызовом Update.

Текст внутри html или значения localization_data может включать теги Dynamic Content, например, {name|string|there} — они разрешаются на основе тегов устройства получателя при фактической отправке email. Этот API не разрешает их; он просто сохраняет и возвращает любой текст, который вы туда поместили.

Объект информации об отправителе

Поле	Тип	Описание
`from`	object	`{ "email": string, "name": string }` — адрес отправителя.
`reply_to`	object	`{ "email": string, "name": string }` — адрес для ответа.

Оба подполя email, если они не пустые, должны быть действительными адресами электронной почты.

Связанные материалы

Notify

Справочник по email-содержимому

Справочник по точкам Customer Journey