Comment intégrer des images de voitures dans vos e-mails avec des URL signées qui ne cassent jamais

Chaque compte Car Image API reçoit un petit mot de Jonathan environ une heure après son premier rendu. La chose la plus évidente à mettre dans cet e-mail, c'est le rendu lui-même : la Porsche 911 2024 ou la Dodge Charger 2006 exacte que la personne vient de demander, comme preuve que l'intégration fonctionne et comme petite démonstration de savoir-faire.

L’e-mail est le pire support possible pour une URL signée. Une page est générée à nouveau à chaque visite ; un e-mail est généré une seule fois et ouvert quand le lecteur s’y met, un jour, un mois ou un an plus tard, souvent via le proxy d’images de Gmail. Les URL de livraison signées que proposait déjà l’API avaient une durée de validité (TTL) maximale de sept jours : le bon plafond pour un navigateur, mais l’assurance d’une image cassée dans la boîte de réception dès la deuxième semaine. Joindre ou intégrer le PNG alourdit chaque message.

Nous voulions une URL qui se comporte comme une image hébergée, continue de fonctionner tant que quelqu’un est susceptible d’ouvrir l’e-mail, et facture malgré tout au compte un montant juste pour ce qu’elle sert réellement.

Nous avons ajouté un seul paramètre à POST /api/v1/image-urls : renew: true. Une URL renouvelable est générée et facturée exactement comme les autres : un crédit, valable ttl_seconds. La différence tient à ce qui se passe après le TTL. Au lieu d'une erreur 403, le premier chargement dans chaque nouvelle fenêtre de ttl_seconds refacture un crédit au compte émetteur et sert l'image ; tous les chargements suivants dans cette fenêtre sont gratuits et peuvent être mis en cache publiquement, comme pour la première fenêtre. Cela continue jusqu'à renews_until, au maximum un an plus tard.

Cette conception a donné trois propriétés, chacune importante pour l’e-mail :

• Rien à renvoyer ni à régénérer. L'URL de l'e-mail reste la même pour toujours. Pas de tâche cron qui réécrit les liens stockés, pas de second e-mail avec une nouvelle image.
• Payez à l'ouverture, pas à la durée. Une période de validité pendant laquelle personne n'ouvre l'e-mail ne coûte rien. Un e-mail lu par une personne un seul jour coûte le crédit pour lequel l'URL a été émise ; un e-mail ouvert chaque semaine pendant un an coûte environ 52 crédits, soit cinq centimes.
• Facturation idempotente. Chaque fenêtre correspond à une ligne du registre identifiée par la clé renew:<url id>:<window>, unique par URL et par fenêtre. Cinquante ouvertures en une semaine, ou deux proxys de messagerie en concurrence lors de la première ouverture, ne sont facturées qu'une seule fois.

Les e-mails de cycle de vie génèrent ces URL via le même chemin de code que l'endpoint public, sous forme de jetons de plateforme : liés à aucune clé API et jamais facturés, puisqu'ils nous appartiennent, mais servis par la même route GET /api/v1/delivery/{token}, avec les mêmes fenêtres de sept jours et la même mise en cache. L'image de l'e-mail du premier rendu, c'est le produit qui fait sa propre démonstration.

Le modèle est en React Email avec des styles inline, car les clients de messagerie suppriment les feuilles de style. Le rendu est placé dans une cellule de tableau bordée sur un fond doux, demandé à 480 pixels et affiché à 240 pour rester net sur les écrans Retina, avec une pastille au-dessus et deux lignes de légende en dessous. Le PNG transparent est la raison d'être du produit, nous le conservons donc ; sur un ancien Outlook qui affiche la transparence en noir, un rendu format: "jpg" sur une cellule à fond uni sert de solution de repli.

Tout le reste du message est du texte : ce qu'est l'URL, pourquoi elle continue de fonctionner, la requête POST exacte pour en générer une pour son propre véhicule, et un lien vers cette page. L'e-mail comporte un lien de désabonnement et les en-têtes List-Unsubscribe, et chaque lien produit est balisé pour que nous puissions voir, dans le rapport d'acquisition, si l'article que vous lisez a fait revenir quelqu'un.

1. Créez les URL côté serveur, au moment de construire l'e-mail. Un appel par véhicule, ou jusqu'à cinquante par appel pour un récapitulatif. Stockez url et renews_until avec le message.
2. Placez l’URL dans une balise <img> avec une largeur, une hauteur et un texte alternatif. Le texte alternatif nomme le véhicule (« Porsche 911 2024, rouge, vue avant trois-quarts »), pas simplement « voiture ».
3. Gardez votre compte approvisionné. Un renouvellement sur un solde vide renvoie 402 et l'image reste cassée jusqu'à l'arrivée des crédits ; la recharge automatique dans le tableau de bord élimine ce risque de panne.

La référence complète des paramètres, les en-têtes de cache et les codes d’erreur se trouvent dans la documentation des URL signées. La compétence d’agent fournie avec le plugin connaît les mêmes règles : un assistant à qui l’on demande de « mettre cette voiture dans la newsletter » génère une URL renouvelable au lieu de coller une clé dans un modèle.