Webhook'lar ve olaylar
Teslim sonuçları doğrudan uygulamanızda
Mail.Land; bir mesaj teslim edildiğinde, ertelendiğinde, geri döndüğünde veya başarısız sonlandığında, bir alıcı şikâyet ettiğinde ve gelen bir e-posta ulaştığında uç noktanıza imzalı bir olay gönderir ve her denemenin günlüğünü tutar.
import crypto from "node:crypto";
// header: X-MLND-Signature: t=1708171200,v1=<hex>
export function verify(rawBody, header, secret) {
if (typeof header !== "string" || header === "") return false;
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const age = Math.abs(Date.now() / 1000 - Number(parts.t));
if (!parts.t || !parts.v1 || age > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Bugün abone olabileceğiniz olaylar
Sekiz olay türü etkin. Hepsine ya da yalnızca ihtiyacınız olanlara abone olun.
| Ne zaman gönderilir | |
|---|---|
| message.delivered | Alıcının posta sunucusu mesajı kabul ettiğinde |
| message.deferred | Teslim şimdilik geciktiğinde; Mail.Land denemeye devam eder |
| message.bounced | Alıcının sunucusu mesajı reddettiğinde; geri dönme türü ve yanıtıyla birlikte |
| message.failed | Mail.Land mesajı dahili bir nedenle veya bir politika gereği başarısız olarak işaretlediğinde; bu olay alıcıyı engelleme listesine eklemez |
| message.complained | Alıcı mesajı bir geri bildirim döngüsüyle spam olarak bildirdiğinde |
| message.outcome_unknown | Mail.Land mesajın teslim kuyruğuna ulaşıp ulaşmadığını henüz bilemediğinde; Mail.Land sonucu sonradan öğrenirse kesin bir olay gelir |
| message.retried | Geri dönen veya başarısız bir mesajı yeniden denediğinizde ve mesaj yeniden kuyruğa girdiğinde |
| inbound.received | Alan adlarınızdan birine bir e-posta geldiğinde ve bir webhook rotasıyla eşleştiğinde |
message.sent, açılmalar ve tıklamalar gibi diğer olay türleri ileride kullanılmak üzere katalogdadır ve henüz gönderilmez. Katalog uç noktası hangilerinin şu an kullanılabildiğini gösterir.
İmzalı ve yalnızca gitmesi gereken yere
Her istek doğrulanabilir; Mail.Land kötüye kullanılabilecek hedefleri reddeder.
Zaman damgalı HMAC-SHA256
X-MLND-Signature başlığı bir zaman damgası ve bu damgayla ham gövdenin imzasını taşır. İmzayı sabit sürede karşılaştırın ve tekrar saldırılarını önlemek için eski zaman damgalarını reddedin.
Yalnızca 443 numaralı portta HTTPS
Özel ve loopback adresleri reddedilir. Yönlendirmeler en fazla üç adım izlenir ve her adım, ona bir şey gönderilmeden önce yeniden denetlenir.
Her webhook için bir gizli anahtar
İmza anahtarı webhook oluşturulurken bir kez gösterilir. Sızarsa yenisini üretin: eskisi hemen çalışmaz hâle gelir.
Uç noktanız çalışmadığında
Başarısız bir teslim varsayılan olarak bu takvimle yeniden denenir. 15 saniye içinde gelen 2xx yanıtı başarı sayılır.
| Denemeden önce bekleme | İlk denemeden bu yana süre | |
|---|---|---|
| 1. deneme | Yok | 0 |
| 2. deneme | Hemen | Yaklaşık 0 |
| 3. deneme | 1 dakika | Yaklaşık 1 dakika |
| 4. deneme | 5 dakika | Yaklaşık 6 dakika |
| 5. deneme | 15 dakika | Yaklaşık 21 dakika |
| 6. deneme | 1 saat | Yaklaşık 1 saat 21 dakika |
Zaman aşımları, ağ hataları ve 408, 429, 500, 502, 503 ile 504 yanıtları yeniden denenir; Retry-After başlığı bir sonraki beklemeyi belirler. 2xx dışındaki diğer yanıtlar kesindir. Başarısız her teslimi günlükten yeniden deneyebilirsiniz.
Geç ya da iki kez gelen olaylar için tasarlandı
Teslim en az bir kezdir ve her zaman sırayla gelmez. Her olay bunu yönetmeniz için gerekeni taşır.
Durum sürümleri
Her mesaj olayı, her değişiklikte artan bir durum sürümü taşır. Tüm mesaj olaylarına abone olur ve bir olayı yalnızca sürümü sakladığınızdan yüksekse uygularsanız, geliş sırası ne olursa olsun durumunuz doğru kalır. Daha az olayla çalışıyorsanız güncel durumu API'den kontrol edin.
Sabit olay kimlikleri
Olay kimliği bir olayın her yeniden denemesinde aynıdır. İşlediğiniz kimlikleri saklayın ve tekrarları atlayın.
Sürümlü yükler
Her olay türünün bir şema sürümü vardır. Mail.Land mevcut bir sürüme yalnızca alan ve başlık ekler; bilinmeyen alanları yok sayan bir alıcı çalışmaya devam eder.
Kontrol ve görünürlük
Webhook'ları panelden veya API üzerinden yönetin.
Ürüne ve alan adına göre filtreleyin
İşlemsel, pazarlama veya gelen e-posta olaylarını, belirli olay türlerini ve tüm alan adlarını ya da yalnızca bazılarını seçin.
Güvenmeden önce test edin
Gerçek imza ve gerçek aktarımla bir test olayı gönderin. Yanıt, gerçek olayların uç noktaya mevcut aboneliğiyle ulaşıp ulaşamayacağını da söyler.
Teslim günlüğü
Her denemeyi durumuyla görün, başarısızları filtreleyin ve bir teslimi elle yeniden deneyin.
Otomatik duraklatma
Varsayılan olarak art arda 10 başarısız denemeden sonra webhook duraklatılır ve panelde bir bildirim alırsınız. Uç noktanız düzeldiğinde yeniden başlatın.
Webhook soruları
Bir mesaj kabul edildiğinde veya gönderildiğinde olay var mı?
Henüz yok. message.sent katalogdadır ama bugün gönderilmez. Gönderim isteğinize verilen API yanıtı mesaj kimliklerini içerir ve aldığınız ilk webhook olayı teslim sonucudur.
Açılma ve tıklama olaylarını alabilir miyim?
Bugün webhook ile alamazsınız. İzlemenin açık olduğu yerlerde açılmalar ve tıklamalar günlüklerinizde ve analitikte görünür; bu olaylar ileride kullanılmak üzere katalogdadır.
Teslim edilen bir mesaj sonradan geri dönerse ne olur?
Olabilir: alıcı sunucu bir mesajı kabul ettikten sonra reddedebilir. Mail.Land bu durumda daha yüksek durum sürümüyle bir geri dönme olayı gönderir; bu yüzden teslim olayından sonra da olayları işlemeye devam edin.
Uç noktam bir gün çalışmazsa ne olur?
Her olay varsayılan olarak yaklaşık 80 dakika içinde en fazla altı kez denenir ve webhook varsayılan olarak art arda 10 başarısız denemeden sonra duraklatılır. Duraklatıldığı sürece ona yeni olay kuyruğa alınmaz. Yeniden başlattıktan sonra başarısız teslimleri günlükten yeniden deneyin, mesajların durumunu API'den kontrol edin ve kaçırdığınız gelen mesajları yeniden gönderin.
Bir isteğin Mail.Land'den geldiğini nasıl doğrularım?
Webhook gizli anahtarınızla zaman damgası, bir nokta ve ham gövde üzerinden HMAC-SHA256 hesaplayın, sonucu v1 değeriyle sabit sürede karşılaştırın ve 5 dakikadan eski zaman damgalarını reddedin. Belgelerde kesin değerlerle bir örnek vardır.
Bir uç nokta yalnızca bazı alan adlarımın olaylarını alabilir mi?
Evet. Webhook'un kapsamını seçili alan adları olarak ayarlayıp bunları listeleyin; yalnızca o alan adlarının olaylarını alır.
Uygulamanızı her teslim sonucuna bağlayın
Ücretsiz bir hesap açın, bir uç nokta ekleyin ve ona bir test olayı gönderin.