База знаний

Шаблоны

Текст письма, написанный один раз, с версиями и множеством отправок: из редактора письма, из вашего собственного кода или агентом.

Подробности

Шаблон принадлежит подключению, а не тому, кто его написал, — именно поэтому первая версия этого механизма была заменена. Та версия была привязана к пользователю: шаблон коллеги был не виден ключу API рабочего пространства, поэтому интеграция не могла отправить то, что видел настроивший её человек, а удаление учётной записи автора уносило с собой шаблоны рабочего пространства. Строки были перенесены, а не выброшены.
Два способа написать тело письма. Дерево блоков над компонентами @react-email/components (Section, Row, Column, Container, Text, Heading, Button, Link, Img, Hr, Markdown, CodeBlock, CodeInline), проверяемое по мере написания, так что неверный узел или небезопасный href отклоняется на том же вызове, который его записал, а не приходит сломанным письмом. Или разметка, которую вы отрендерили сами: если ваши шаблоны уже являются компонентами react-email в вашем собственном репозитории, рендерите их там с помощью @react-email/render и отправляйте HTML — он очищается один раз при публикации версии.
Двадцать три заготовки и одна пустая — в галерее, а не в меню, потому что перед выбором на них нужно посмотреть, и поэтому каждая карточка показывает само письмо. Приветствия и подтверждения, чеки и счета, доставка и продления, дайджесты и объявления — разложенные под четырьмя заголовками, и каждая открывается в визуальном редакторе, где любой элемент можно перемещать, перестилизовывать и удалять. Что бы вы ни выбрали, оно приходит черновиком, поэтому отправить ничего нельзя, пока вы это не опубликуете.
Галерея — единственная часть всего этого, которая есть только в приложении. Вызывающая сторона, обращающаяся к шаблонам из вашего собственного кода или от агента, отправляет тело письма (блочный документ или вашу собственную разметку), а не называет заготовку, так что эти двадцать три — место, с которого можно начать, а не каталог для установки.
Именованные слоты и именованные пропсы — два вида пустых мест, записываемые как {{key}} в теле и в теме. Слот заполняет тот, кто редактирует шаблон, и у него есть значение по умолчанию, так что отправка, не называющая ничего, всё равно отрендерится. Проп передаётся при отправке, и помеченный как обязательный отклоняет отправку, когда его нет: 422, и письмо не уходит. Ради этого отказа его и объявляют: альтернатива — письмо, ушедшее с пустотой там, где должен быть номер заказа, о чём ничто не сообщит и что никто не сможет отозвать.
Опубликованная версия заморожена. Правка тела опубликованного шаблона создаёт новый черновик, а не переписывает то, что работает, поэтому отправки продолжают разрешаться в то же, во что разрешались вчера, пока кто-нибудь не опубликует, а отправка, закрепляющая номер версии, не затрагивается и тогда. Тело компилируется при публикации — именно поэтому шаблон, который не рендерится, ломается у того, кто его публикует, а не у получателя.
Предпросмотр рендерит ровно то, что дала бы отправка, ничего не отправляя, и сообщает о том, что ещё пусто, вместо отказа. Шаблон, который предпросматривают, обычно ещё пишется, и автору, заполняющему по одному блоку за раз, не должно требоваться удовлетворить каждый проп, чтобы увидеть сделанное.
У каждого шаблона своя запись о том, что он отправил: сколько писем ушло за последние семь, тридцать или девяносто дней, какие из них открыли, а по каким кликнули, ряд по дням и разбивка по тому, откуда пришла каждая отправка: редактор письма, ваш код, агент или очередь. Каждый показатель называет собственный знаменатель, а не заимствует чужой, потому что они действительно разные: открытия считаются по письмам, несущим пиксель, клики — по письмам, несущим переписанную ссылку, а письмо может нести одно без другого. Предпросмотр не записывается вовсе, а тестовая отправка считается отдельно и не входит ни в одну цифру, потому что она никуда не ушла.
Эта запись честна в том, чего она не видит, — и именно поэтому той половине, которую она видит, можно верить. Отправка сопоставляется со своей записью о доставке по самой отправке, и только почта, отправленная из вашего собственного кода или из очереди, несёт такую запись. Письмо, отправленное из редактора письма, агентом или ассистентом, — нет. Поэтому шаблон, используемый в основном из редактора письма, приходит с большинством несопоставленных отправок, и число несопоставленных показывается как отдельная цифра, а не подмешивается как «никто не открыл».
Четыре поверхности над одним сервисом, так что у вопроса «что значит опубликовать» один ответ, а не три, совпадающих сегодня. Кнопка «Шаблоны» в редакторе письма предлагает опубликованные и ЗАМЕНЯЕТ письмо тем, что вы выбрали, а не вставляет его внутрь: отправка называет шаблон, версия закрепляется в момент выбора, а тело рендерится там, где его писали, поэтому публикация между выбором и нажатием не может изменить то, что уйдёт, а вёрстка, которую редактор письма не смог бы удержать, остаётся целой. Там вы заполняете значения, а не тело. /templates — это девять эндпоинтов за скоупами templates:read и templates:write, обёрнутые метод в метод в SDK. Для отправки нужно разрешение на отправку вдобавок к разрешению на шаблоны, так что ключ, выданный инструменту для копирайтинга, может писать и публиковать, не имея возможности никому отправить письмо. MCP-сервер несёт пять инструментов: список, чтение, предпросмотр, создание и отправка. Инструмента для обновления, удаления или публикации существующего намеренно нет. Правка создаёт черновик, в который следующая отправка не разрешится, а удаление нельзя отменить. Редактирование сохранённого тела — это экран: /workspace/templates несёт блочный холст с палитрой и инспектором, живой предпросмотр рядом и «Сохранить» и «Опубликовать» как отдельные действия — именно это делает опубликованную версию тем, что можно не трогать, пока работаешь над следующей.
200 шаблонов на подключение, блочный документ не более 500 блоков, восемь уровней вложенности, 20 000 символов в одном значении, 100 слотов и 100 пропсов; тело, отправленное как разметка, — не более миллиона символов, тема — 998. Каждое из этих ограничений — защита от сорвавшегося скрипта, а не лимит тарифа; каждое отклоняет запрос сообщением, называющим то число, на котором оно сработало, и ничто в шаблонах не спрятано за уровнем тарифа.