Как встраивать изображения автомобилей в письма с помощью подписанных URL, которые никогда не ломаются

Каждый аккаунт в Car Image API примерно через час после первого рендера получает короткое письмо от Джонатана. Самое очевидное, что можно вложить в это письмо, — сам рендер: тот самый Porsche 911 2024 года или Dodge Charger 2006 года, который человек только что запросил, как доказательство того, что интеграция работает, и как маленький повод похвастаться.

Электронное письмо — худшее из возможных мест для подписанного URL. Страница заново отрисовывается при каждом посещении; письмо отрисовывается один раз и открывается, когда до него дойдут руки у читателя, — через день, месяц или год, часто через прокси изображений Gmail. Подписанные URL доставки, которые API уже предлагал, имели максимальный TTL в семь дней — разумный предел для браузера, но гарантия битого изображения во входящих уже на второй неделе. Вложение PNG или встраивание его в письмо раздувает каждое сообщение.

Нам был нужен URL, который ведёт себя как размещённое изображение, работает столько, сколько кто-либо может открыть письмо, и при этом честно списывает со счёта только за то, что действительно отдаёт.

Мы добавили в POST /api/v1/image-urls один флаг: renew: true. Обновляемый URL создаётся точно так же, как любой другой, учитывает своё изображение как изображение автомобиля за месяц и действует в течение ttl_seconds. Разница в том, что происходит после истечения TTL. Вместо ответа 403 первая загрузка в каждом новом окне длиной ttl_seconds обновляет URL и отдаёт изображение; при обновлении изображение учитывается один раз в том месяце, на который оно приходится, и больше ничего не списывается, если в этом месяце оно уже учтено. Все последующие загрузки в этом окне допускают публичное кэширование, так же как в первом окне. Так продолжается до renews_until — не более чем на год вперёд.

Из такой архитектуры вытекли три свойства, и каждое оказалось важным для писем:

• Ничего не нужно пересылать или выпускать заново. URL в письме остаётся неизменным навсегда. Никаких cron-задач, переписывающих сохранённые ссылки, никаких повторных писем со свежим изображением.
• Считаются открытия, а не время. Окно, которое никто не открыл, не учитывается. Письмо, прочитанное одним человеком в один день, — это одно изображение автомобиля, для которого оно создано; письмо, открываемое каждую неделю в течение года, учитывает это изображение один раз в каждом месяце открытия — максимум двенадцать раз.
• Идемпотентный учёт. Каждое окно записывается один раз с ключом renew:<url id>:<window>, уникальным для каждого URL и окна. Пятьдесят открытий за неделю или два почтовых прокси, одновременно открывающих письмо впервые, учитываются один раз.

Письма жизненного цикла создают эти URL тем же кодом, что и публичный эндпоинт, в виде платформенных токенов: они не привязаны ни к одному API-ключу и никогда не тарифицируются, потому что принадлежат нам, но обслуживаются тем же маршрутом GET /api/v1/delivery/{token}, с теми же семидневными окнами и тем же кешированием. Изображение в письме о первом рендере — это продукт, демонстрирующий сам себя.

Шаблон написан на React Email со встроенными стилями, потому что почтовые клиенты удаляют таблицы стилей. Рендер размещён в ячейке таблицы с рамкой на мягком фоне: он запрашивается с размером 480 пикселей и показывается в 240, чтобы оставаться чётким на Retina-экранах; над ним — плашка, под ним — две строки подписи. Прозрачный PNG — вся суть продукта, поэтому мы его сохраняем; для старого Outlook, который закрашивает альфа-канал чёрным, запасной вариант — рендер с format: "jpg" на сплошном фоне ячейки.

Всё остальное в письме — текст: что это за URL, почему он продолжает работать, точный POST-запрос, чтобы получить такой же для своего автомобиля, и ссылка на эту страницу. В письме есть ссылка для отписки и заголовки List-Unsubscribe, а каждая ссылка на продукт размечена, чтобы в отчёте о привлечении мы видели, вернула ли кого-нибудь история, которую вы читаете.

1. Создавайте на сервере, когда формируете письмо. Один вызов на автомобиль или до пятидесяти за вызов для дайджеста. Сохраняйте url и renews_until вместе с сообщением.
2. Вставьте URL в <img> с указанием ширины, высоты и альтернативного текста. В альтернативном тексте назовите автомобиль («2024 Porsche 911, красный, вид спереди в три четверти»), а не просто «автомобиль».
3. Следите за лимитом аккаунта. Продление засчитывает изображение один раз в том месяце, на который оно приходится; если изображения автомобилей по тарифу исчерпаны, оно возвращает 402 до сброса лимита 1-го числа, поэтому подбирайте тариф под количество отдаваемых изображений.

Полный справочник параметров, заголовки кеширования и коды ошибок — в документации по подписанным URL. Навык агента, который поставляется с плагином, знает те же правила, поэтому ассистент, которого попросили «добавить этот автомобиль в рассылку», создаёт обновляемый URL, а не вставляет ключ в шаблон.