Come inserire immagini di auto nelle email con URL firmati che non smettono mai di funzionare

Ogni account su Car Image API riceve un breve messaggio da Jonathan circa un’ora dopo il primo render. La cosa più ovvia da inserire in quell’email è il render stesso: l’esatta Porsche 911 del 2024 o Dodge Charger del 2006 appena richiesta, come prova che l’integrazione funziona e come piccolo vanto.

L'email è la superficie peggiore possibile per un URL firmato. Una pagina viene renderizzata di nuovo a ogni visita; un'email viene renderizzata una sola volta e aperta quando il lettore ci arriva, un giorno, un mese o un anno dopo, spesso tramite il proxy delle immagini di Gmail. Gli URL di consegna firmati già offerti dall'API avevano un TTL massimo di sette giorni: il limite giusto per un browser, ma che garantisce un'immagine non visualizzata nella casella di posta entro la seconda settimana. Allegare o incorporare il PNG appesantisce ogni messaggio.

Volevamo un URL che si comportasse come un'immagine ospitata, continuasse a funzionare finché qualcuno avesse potuto aprire l'email, e addebitasse comunque all'account in modo equo ciò che effettivamente fornisce.

Abbiamo aggiunto un solo flag a POST /api/v1/image-urls: renew: true. Un URL rinnovabile viene generato esattamente come qualsiasi altro, conta la sua immagine come immagine di veicolo del mese ed è valido per ttl_seconds. La differenza sta in ciò che accade dopo il TTL. Invece di un 403, il primo caricamento in ogni nuova finestra di ttl_seconds rinnova l’URL e serve l’immagine; un rinnovo conta l’immagine una volta nel mese in cui avviene, e nulla di più se era già stata conteggiata quel mese. Ogni caricamento successivo in quella finestra è memorizzabile nella cache pubblica, come nella prima finestra. Questo continua fino a renews_until, fino a un anno dopo.

Da quel design sono emerse tre proprietà, e ognuna era importante per l'email:

• Niente da reinviare o rigenerare. L’URL nell’email resta lo stesso per sempre. Nessun cron job che riscrive i link salvati, nessuna seconda email con un’immagine nuova.
• Si contano le aperture, non il tempo. Una finestra che nessuno apre non conta nulla. Un’email letta da una persona in un solo giorno equivale all’unica immagine di veicolo per cui è stata generata; una aperta ogni settimana per un anno conta quell’immagine una volta in ogni mese in cui viene aperta, al massimo dodici volte.
• Conteggio idempotente. Ogni finestra viene registrata una sola volta, con chiave renew:<url id>:<window>, univoca per URL e finestra. Cinquanta aperture in una settimana, o due proxy di posta che competono alla prima apertura, contano una volta sola.

Le email di ciclo di vita generano questi URL tramite lo stesso percorso di codice usato dall'endpoint pubblico, come token di piattaforma: non legati ad alcuna chiave API e mai fatturati, perché sono nostri, ma serviti dalla stessa route GET /api/v1/delivery/{token}, con le stesse finestre di sette giorni e la stessa cache. L'immagine nell'email del primo render è il prodotto che dimostra se stesso.

Il template è realizzato con React Email e stili inline, perché i client di posta rimuovono i fogli di stile. Il render si trova in una cella di tabella con bordo su uno sfondo tenue, richiesto a 480 pixel e mostrato a 240 così resta nitido sugli schermi retina, con un’etichetta a pillola sopra e due righe di didascalia sotto. Il PNG trasparente è il senso stesso del prodotto, quindi lo manteniamo; sulle vecchie versioni di Outlook che rendono nero il canale alfa, la soluzione di riserva è un render format: "jpg" su uno sfondo di cella a tinta unita.

Tutto il resto del messaggio è testo: che cos’è l’URL, perché continua a funzionare, la POST esatta per generarne uno per il proprio veicolo e un link a questa pagina. L’email contiene un link per annullare l’iscrizione e le intestazioni List-Unsubscribe, e ogni link al prodotto è tracciato, così nel report di acquisizione possiamo vedere se la storia che sta leggendo ha riportato qualcuno da noi.

1. Generi gli URL lato server, quando crea l’email. Una chiamata per veicolo, oppure fino a cinquanta per chiamata per un riepilogo. Salvi url e renews_until insieme al messaggio.
2. Inserisca l'URL in un <img> con larghezza, altezza e testo alternativo. Il testo alternativo indica il veicolo ("Porsche 911 2024, rossa, vista anteriore di tre quarti"), non "auto".
3. Mantenga l'account attivo. Un rinnovo conta l'immagine una volta nel mese in cui avviene; se le immagini di veicoli del piano sono esaurite risponde 402 finché la quota non si azzera il 1° del mese, quindi dimensioni il piano in base alle immagini che serve.

Il riferimento completo dei parametri, gli header di cache e i codici di errore si trovano nella documentazione sugli URL firmati. La skill per agenti inclusa nel plugin conosce le stesse regole, quindi un assistente a cui si chiede di "mettere quest'auto nella newsletter" genera un URL rinnovabile invece di incollare una chiave in un template.