Auto-afbeeldingen in e-mail insluiten met signed URLs die nooit breken

Elk account op Car Image API krijgt ongeveer een uur na de eerste render een kort bericht van Jonathan. Het meest voor de hand liggende om in die e-mail te zetten is de render zelf: precies de 2024 Porsche 911 of 2006 Dodge Charger waar de persoon net om vroeg, als bewijs dat de integratie werkt en als klein beetje opschepperij.

E-mail is de slechtst denkbare plek voor een ondertekende URL. Een pagina wordt bij elk bezoek opnieuw gerenderd; een e-mail wordt één keer gerenderd en geopend wanneer de lezer eraan toekomt, een dag, een maand of een jaar later, vaak via de afbeeldingsproxy van Gmail. De ondertekende bezorg-URL's die de API al aanbood, hadden een maximale TTL van zeven dagen: het juiste plafond voor een browser, maar een gegarandeerd kapotte afbeelding in een inbox vanaf week twee. De PNG als bijlage of inline meesturen maakt elk bericht onnodig zwaar.

Wat we wilden, was een URL die zich gedraagt als een gehoste afbeelding, blijft werken zolang iemand de e-mail zou kunnen openen, en het account toch eerlijk laat betalen voor wat er daadwerkelijk wordt geleverd.

We hebben één vlag toegevoegd aan POST /api/v1/image-urls: renew: true. Een vernieuwbare URL wordt precies zo aangemaakt als elke andere, telt zijn afbeelding als voertuigafbeelding van de maand en is geldig gedurende ttl_seconds. Het verschil zit in wat er na de TTL gebeurt. In plaats van een 403 vernieuwt de eerste keer laden in elk nieuw venster van ttl_seconds de URL en levert die de afbeelding; een vernieuwing telt de afbeelding één keer in de maand waarin die plaatsvindt, en verder niets als de afbeelding die maand al was geteld. Elke volgende keer laden in dat venster is openbaar cachebaar, net als in het eerste venster. Dat gaat door tot renews_until, maximaal een jaar vooruit.

Uit dat ontwerp volgden drie eigenschappen, en elk ervan was belangrijk voor e-mail:

• Niets opnieuw te versturen of aan te maken. De URL in de e-mail blijft voor altijd dezelfde URL. Geen cronjob die opgeslagen links herschrijft, geen tweede e-mail met een nieuwe afbeelding.
• Tel openingen, geen tijd. Een venster waarin niemand de e-mail opent, telt niets. Een e-mail die door één persoon op één dag wordt gelezen, is de ene voertuigafbeelding waarvoor hij is aangemaakt; een e-mail die een jaar lang elke week wordt geopend, telt die afbeelding één keer in elke maand waarin hij wordt geopend, hooguit twaalf keer.
• Idempotent tellen. Elk venster wordt één keer vastgelegd, met sleutel renew:<url id>:<window>, uniek per URL en venster. Vijftig keer openen in een week, of twee mailproxy’s die tegelijk de eerste opening verwerken, tellen één keer.

De lifecycle-e-mails maken deze URL's aan via hetzelfde codepad als het openbare endpoint, als platformtokens: aan geen enkele API-sleutel gekoppeld en nooit gefactureerd, omdat ze van ons zijn, maar geleverd via exact dezelfde route GET /api/v1/delivery/{token}, met dezelfde vensters van zeven dagen en dezelfde caching. De afbeelding in de e-mail over de eerste render is het product dat zichzelf demonstreert.

De template is React Email met inline styles, omdat mailclients stylesheets verwijderen. De render staat in een tabelcel met rand op een zachte achtergrond, opgevraagd op 480 pixels en getoond op 240, zodat hij scherp blijft op retina-schermen, met een label erboven en twee bijschriftregels eronder. Transparante PNG is de kern van het product, dus die houden we; in een oude Outlook die alfa als zwart weergeeft, is een render met format: "jpg" op een effen celachtergrond de fallback.

Al het andere in het bericht is tekst: wat de URL is, waarom die blijft werken, de exacte POST om er een aan te maken voor hun eigen voertuig, en een link naar deze pagina. De e-mail bevat een afmeldlink en de List-Unsubscribe-headers, en elke productlink is getagd, zodat we in het acquisitierapport kunnen zien of het verhaal dat u nu leest iemand heeft teruggebracht.

1. Maak de URL's server-side aan, wanneer u de e-mail opbouwt. Eén aanroep per voertuig, of maximaal vijftig per aanroep voor een overzichtsmail. Sla url en renews_until op bij het bericht.
2. Plaats de URL in een <img> met breedte, hoogte en alt-tekst. De alt-tekst noemt het voertuig ("2024 Porsche 911, rood, driekwartaanzicht van voren"), niet "auto".
3. Houd het account op peil. Een verlenging telt de afbeelding eenmaal in de maand waarin die valt; als de voertuigafbeeldingen van het abonnement op zijn, antwoordt de URL met 402 totdat het tegoed op de 1e wordt gereset, dus stem het abonnement af op het aantal afbeeldingen dat u levert.

De volledige parameterreferentie, cachingheaders en foutcodes staan in de documentatie over signed URL's. De agentskill die met de plug-in wordt meegeleverd, kent dezelfde regels, zodat een assistent die wordt gevraagd om "deze auto in de nieuwsbrief te zetten" een vernieuwbare URL aanmaakt in plaats van een sleutel in een template te plakken.