Cómo insertar imágenes de coches en emails con URL firmadas que nunca fallan

Cada cuenta de Car Image API recibe una breve nota de Jonathan aproximadamente una hora después de su primer render. Lo obvio es incluir en ese correo el propio render: el Porsche 911 de 2024 o el Dodge Charger de 2006 exacto que la persona acaba de pedir, como prueba de que la integración funcionó y como un pequeño alarde.

El correo electrónico es el peor medio posible para una URL firmada. Una página se vuelve a renderizar en cada visita; un correo se renderiza una sola vez y se abre cuando el lector llega a él, un día, un mes o un año después, a menudo a través del proxy de imágenes de Gmail. Las URL de entrega firmadas que la API ya ofrecía tenían un TTL máximo de siete días, que es el límite adecuado para un navegador, pero garantiza una imagen rota en la bandeja de entrada a partir de la segunda semana. Adjuntar o incrustar el PNG aumenta el tamaño de cada mensaje.

Lo que queríamos era una URL que se comportara como una imagen alojada, siguiera funcionando mientras alguien pudiera abrir el correo y, aun así, cobrara a la cuenta de forma justa por lo que realmente sirve.

Añadimos un indicador a POST /api/v1/image-urls: renew: true. Una URL renovable se genera y se cobra exactamente igual que cualquier otra: un crédito, válida durante ttl_seconds. La diferencia está en lo que ocurre después del TTL. En lugar de un 403, la primera carga en cada nueva ventana de ttl_seconds vuelve a cobrar un crédito a la cuenta emisora y sirve la imagen; cualquier otra carga en esa ventana es gratuita y puede almacenarse en caché públicamente, igual que en la primera ventana. Esto continúa hasta renews_until, como máximo un año después.

De ese diseño surgieron tres propiedades, y cada una resultó importante para el correo electrónico:

• Nada que reenviar ni volver a generar. La URL del correo es la URL para siempre. Sin tareas cron que reescriban enlaces guardados ni un segundo correo con una imagen nueva.
• Pague por aperturas, no por tiempo. Una ventana de validez que nadie abre no cuesta nada. Un correo leído por una persona un solo día cuesta el crédito para el que se generó; uno abierto cada semana durante un año cuesta unos 52 créditos, cinco centavos.
• Facturación idempotente. Cada ventana es una fila del registro contable con la clave renew:<url id>:<window>, única por URL y ventana. Cincuenta aperturas en una semana, o dos proxies de correo compitiendo en la primera apertura, se pagan una sola vez.

Los correos del ciclo de vida generan estas URL por la misma ruta de código que usa el endpoint público, como tokens de plataforma: no están vinculados a ninguna clave de API y nunca se facturan, porque son nuestros, pero se sirven por la misma ruta GET /api/v1/delivery/{token}, con las mismas ventanas de siete días y el mismo almacenamiento en caché. La imagen del correo del primer render es el producto demostrándose a sí mismo.

La plantilla usa React Email con estilos en línea, porque los clientes de correo eliminan las hojas de estilo. El render va en una celda de tabla con borde sobre un fondo suave, solicitado a 480 píxeles y mostrado a 240 para que se vea nítido en pantallas retina, con una etiqueta encima y dos líneas de pie debajo. El PNG transparente es la razón de ser del producto, así que lo mantenemos; en un Outlook antiguo que pinta el canal alfa de negro, la alternativa es un render con format: "jpg" sobre una celda con fondo sólido.

Todo lo demás en el mensaje es texto: qué es la URL, por qué sigue funcionando, el POST exacto para generar una para su propio vehículo y un enlace a esta página. El correo incluye un enlace para darse de baja y las cabeceras List-Unsubscribe, y cada enlace al producto está etiquetado para que podamos ver, en el informe de adquisición, si la historia que está leyendo hizo volver a alguien.

1. Genérelas en el servidor, al crear el correo. Una llamada por vehículo, o hasta cincuenta por llamada para un resumen. Guarde url y renews_until junto con el mensaje.
2. Ponga la URL en un <img> con ancho, alto y texto alternativo. El texto alternativo nombra el vehículo ("Porsche 911 2024, rojo, vista frontal de tres cuartos"), no "coche".
3. Mantenga la cuenta con saldo. Una renovación con saldo cero responde 402 y la imagen sigue rota hasta que lleguen créditos; la recarga automática en el panel elimina ese modo de fallo.

La referencia completa de parámetros, las cabeceras de caché y los códigos de error están en la documentación de URL firmadas. La skill de agente que se incluye con el plugin conoce las mismas reglas, así que un asistente al que se le pide "pon este coche en el boletín" genera una URL renovable en lugar de pegar una clave en una plantilla.