Jak osadzać zdjęcia samochodów w e-mailach za pomocą podpisanych URL-i, które nigdy nie przestają działać

Każde konto w Car Image API otrzymuje od Jonathana krótką wiadomość mniej więcej godzinę po pierwszym renderze. Najbardziej oczywistą rzeczą do umieszczenia w tym e-mailu jest sam render: dokładnie to Porsche 911 z 2024 roku czy Dodge Charger z 2006 roku, o które dana osoba właśnie poprosiła – jako dowód, że integracja działa, i jako drobna przechwałka.

E-mail to najgorsze możliwe miejsce dla podpisanego URL. Strona jest renderowana ponownie przy każdej wizycie; e-mail jest renderowany raz i otwierany wtedy, gdy odbiorca do niego dotrze – dzień, miesiąc lub rok później, często przez proxy obrazów Gmaila. Podpisane URL-e dostarczania, które API już oferowało, miały maksymalny TTL wynoszący siedem dni – to właściwy limit dla przeglądarki, ale w skrzynce odbiorczej gwarantuje niewyświetlający się obraz już w drugim tygodniu. Dołączanie PNG jako załącznika lub osadzanie go w treści zwiększa rozmiar każdej wiadomości.

Chcieliśmy URL-a, który zachowuje się jak hostowany obraz, działa tak długo, jak ktokolwiek może otworzyć e-mail, i nadal uczciwie obciąża konto za to, co faktycznie serwuje.

Do POST /api/v1/image-urls dodaliśmy jedną flagę: renew: true. Odnawialny URL jest generowany dokładnie tak jak każdy inny, nalicza swój obraz jako obraz pojazdu w danym miesiącu i jest ważny przez ttl_seconds. Różnica dotyczy tego, co dzieje się po upływie TTL. Zamiast błędu 403 pierwsze wczytanie w każdym nowym oknie ttl_seconds odnawia URL i serwuje obraz; odnowienie nalicza obraz raz w miesiącu, w którym nastąpi, i nic więcej, jeśli obraz został już naliczony w tym miesiącu. Każde kolejne wczytanie w tym oknie może być publicznie buforowane, tak samo jak w pierwszym oknie. Trwa to do renews_until, maksymalnie rok naprzód.

Z tego projektu wynikły trzy właściwości i każda z nich miała znaczenie dla e-maili:

• Nic do ponownego wysyłania ani generowania. URL w e-mailu pozostaje ten sam na zawsze. Żadnego zadania cron przepisującego zapisane linki, żadnego drugiego e-maila z nowym obrazem.
• Liczą się otwarcia, nie czas. Okno, którego nikt nie otworzy, niczego nie nalicza. E-mail przeczytany przez jedną osobę jednego dnia to jeden obraz pojazdu, dla którego został wygenerowany; e-mail otwierany co tydzień przez rok nalicza ten obraz raz w każdym miesiącu, w którym zostanie otwarty — najwyżej dwanaście razy.
• Idempotentne zliczanie. Każde okno jest zapisywane raz, z kluczem renew:<url id>:<window>, unikalnym dla URL-a i okna. Pięćdziesiąt otwarć w tygodniu albo dwa proxy pocztowe ścigające się przy pierwszym otwarciu liczą się jako jedno.

E-maile cyklu życia generują te adresy URL tą samą ścieżką kodu, z której korzysta publiczny endpoint, jako tokeny platformy: niepowiązane z żadnym kluczem API i nigdy nierozliczane, bo są nasze, ale obsługiwane przez identyczną trasę GET /api/v1/delivery/{token}, z identycznymi siedmiodniowymi oknami i identycznym buforowaniem. Obraz w e-mailu o pierwszym renderze to produkt prezentujący sam siebie.

Szablon powstał w React Email ze stylami inline, ponieważ klienty poczty usuwają arkusze stylów. Render znajduje się w obramowanej komórce tabeli na delikatnym tle; jest pobierany w rozmiarze 480 px i wyświetlany w rozmiarze 240 px, dzięki czemu pozostaje ostry na ekranach retina. Nad nim znajduje się etykieta w kształcie pigułki, a pod nim dwie linie podpisu. Przezroczysty PNG to sedno produktu, więc go zachowujemy; w starym Outlooku, który wypełnia kanał alfa na czarno, rozwiązaniem awaryjnym jest render format: "jpg" na jednolitym tle komórki.

Cała reszta wiadomości to tekst: czym jest ten URL, dlaczego wciąż działa, dokładne żądanie POST pozwalające wygenerować taki URL dla własnego pojazdu oraz link do tej strony. E-mail zawiera link do wypisania się i nagłówki List-Unsubscribe, a każdy link do produktu jest oznaczony, dzięki czemu w raporcie pozyskania widzimy, czy historia, którą Państwo czytają, sprowadziła kogoś z powrotem.

1. Generowanie po stronie serwera podczas tworzenia e-maila. Jedno wywołanie na pojazd lub do pięćdziesięciu pojazdów w jednym wywołaniu w przypadku zestawienia. Należy zapisać url i renews_until razem z wiadomością.
2. URL należy umieścić w <img> z szerokością, wysokością i tekstem alternatywnym. Tekst alternatywny nazywa pojazd („2024 Porsche 911, czerwony, widok z przodu w trzech czwartych”), a nie „samochód”.
3. Konto musi mieć dostępny limit. Odnowienie liczy obraz raz w miesiącu, w którym nastąpi; jeśli obrazy pojazdów z planu zostały wykorzystane, zwraca 402 do czasu odnowienia limitu 1. dnia miesiąca, dlatego plan należy dobrać do liczby wyświetlanych obrazów.

Pełny opis parametrów, nagłówki cache i kody błędów znajdują się w dokumentacji podpisanych URL-i. Umiejętność agenta (skill) dołączona do wtyczki zna te same zasady, więc asystent poproszony o „wstaw ten samochód do newslettera” generuje odnawialny URL zamiast wklejać klucz do szablonu.