Hiç bozulmayan imzalı URL'lerle e-postalara araç görselleri nasıl eklenir

Car Image API'deki her hesap, ilk render'ından yaklaşık bir saat sonra Jonathan'dan kısa bir not alır. Bu e-postaya konulacak en bariz şey render'ın kendisidir: kişinin az önce istediği 2024 Porsche 911 ya da 2006 Dodge Charger'ın ta kendisi; hem entegrasyonun çalıştığının kanıtı hem de küçük bir övünme vesilesi olarak.

E-posta, imzalı bir URL için olabilecek en kötü ortamdır. Bir sayfa her ziyarette yeniden oluşturulur; bir e-posta ise bir kez oluşturulur ve okuyucu ne zaman fırsat bulursa, bir gün, bir ay veya bir yıl sonra, çoğu zaman Gmail’in görsel proxy’si üzerinden açılır. API’nin halihazırda sunduğu imzalı teslim URL’lerinin maksimum TTL’si yedi gündü; bu, bir tarayıcı için doğru üst sınırdır ancak gelen kutusunda ikinci haftaya varmadan bozuk bir görseli garanti eder. PNG’yi ek olarak göndermek veya satır içine gömmek ise her iletiyi şişirir.

İstediğimiz şey, barındırılan bir görsel gibi davranan, e-postayı açabilecek biri olduğu sürece çalışmaya devam eden ve yine de hesaba gerçekten sunduğu şey için adil ücret yansıtan bir URL'ydi.

POST /api/v1/image-urls uç noktasına tek bir bayrak ekledik: renew: true. Yenilenebilir bir URL tam olarak diğerleri gibi oluşturulur, görselini ayın bir araç görseli olarak sayar ve ttl_seconds boyunca geçerlidir. Fark, TTL dolduktan sonra olanlardadır. 403 yerine, her yeni ttl_seconds penceresindeki ilk yükleme URL'yi yeniler ve görseli sunar; bir yenileme görseli denk geldiği ayda bir kez sayar, o ay zaten sayılmışsa başka bir şey saymaz. O penceredeki sonraki her yükleme, ilk pencerede olduğu gibi herkese açık olarak önbelleğe alınabilir. Bu durum, en fazla bir yıl sonrasına kadar, renews_until zamanına dek sürer.

Bu tasarımdan üç özellik ortaya çıktı ve her biri e-posta için önemliydi:

• Yeniden gönderilecek ya da yeniden oluşturulacak bir şey yok. E-postadaki URL sonsuza dek aynı kalır. Kayıtlı bağlantıları yeniden yazan bir cron işi de, yeni görselle gönderilen ikinci bir e-posta da yok.
• Süreyi değil, açılmaları sayın. Kimsenin açmadığı bir pencere hiçbir şey saymaz. Bir kişinin tek bir günde okuduğu bir e-posta, oluşturulduğu tek araç görselidir; bir yıl boyunca her hafta açılan bir e-posta ise o görseli açıldığı her ayda bir kez, en fazla on iki kez sayar.
• İdempotent sayım. Her zaman aralığı, URL ve zaman aralığı başına benzersiz olan renew:<url id>:<window> anahtarıyla bir kez kaydedilir. Bir haftada elli açılma ya da ilk açılışta yarışan iki e-posta proxy'si tek sayılır.

Yaşam döngüsü e-postaları bu URL'leri, herkese açık uç noktanın kullandığı kod yolunun aynısı üzerinden platform token'ları olarak oluşturur. Bu token'lar hiçbir API anahtarına bağlı değildir ve bize ait oldukları için asla faturalandırılmaz. Ancak aynı GET /api/v1/delivery/{token} rotasıyla, aynı yedi günlük sürelerle ve aynı önbelleğe alma ayarlarıyla sunulurlar. İlk render e-postasındaki görsel, ürünün kendi kendini tanıtmasıdır.

Şablon, satır içi stillerle React Email kullanır; çünkü e-posta istemcileri stil sayfalarını kaldırır. Render, yumuşak bir arka plan üzerindeki kenarlıklı bir tablo hücresinde yer alır; retina ekranlarda net kalması için 480 piksel olarak istenir ve 240 piksel olarak gösterilir; üstünde bir etiket, altında iki satır açıklama bulunur. Şeffaf PNG ürünün asıl amacıdır, bu yüzden onu koruyoruz; alfa kanalını siyaha boyayan eski Outlook sürümlerinde ise düz renkli bir hücre arka planı üzerinde format: "jpg" render yedek çözümdür.

Mesajdaki diğer her şey metindir: URL'nin ne olduğu, neden çalışmaya devam ettiği, kendi araçları için bir URL oluşturmak üzere gönderilecek POST isteğinin tam hâli ve bu sayfaya bir bağlantı. E-postada bir abonelikten çıkma bağlantısı ve List-Unsubscribe başlıkları bulunur; her ürün bağlantısı etiketlenir, böylece edinim raporunda okuduğunuz bu hikâyenin birini geri getirip getirmediğini görebiliriz.

1. E-postayı oluştururken sunucu tarafında üretin. Araç başına bir çağrı ya da özet e-posta için çağrı başına elliye kadar. url ve renews_until değerlerini mesajla birlikte saklayın.
2. URL'yi genişlik, yükseklik ve alt metinle birlikte bir <img> içine yerleştirin. Alt metin "araba" değil, aracın adını vermelidir ("2024 Porsche 911, kırmızı, ön üç çeyrek görünüm").
3. Hesabınızda yeterli kota bulundurun. Bir yenileme, görseli denk geldiği ayda bir kez sayar; planın araç görselleri tükenmişse kota ayın 1'inde sıfırlanana kadar 402 yanıtı verir, bu yüzden planı sunduğunuz görsellere göre boyutlandırın.

Tüm parametre referansı, önbellek başlıkları ve hata kodları imzalı URL belgelerinde yer alır. Eklentiyle birlikte gelen ajan becerisi de aynı kuralları bilir; böylece "bu aracı bültene ekle" denen bir asistan, şablona anahtar yapıştırmak yerine yenilenebilir bir URL oluşturur.