Yeniden Deneme Mantığı

Bir webhook teslimi başarısız olduğunda, MailLand artan gecikmelerle otomatik olarak yeniden dener. Bu sayfa yeniden deneme programını, teslim durumlarını, hata yönetimini ve teslimatları nasıl izleyip elle yeniden deneyeceğinizi kapsamaktadır.

Yeniden Deneme ProgramıBölüm bağlantısını kopyala

Bu bölüm, durable dispatcher tarafından teslim edilen tüm olayları kapsar: message.*, suppression.*, account.* ve inbound.received. Gelen olaylara özgü kısımlar için aşağıdaki Gelen Kutusu Teslimatları bölümüne bakın.

MailLand başarısız bir teslimatı toplamda 6 defaya kadar, her yeniden denemeden önce artan bir gecikmeyle yeniden dener:

6. deneme başarısız olursa teslimat kalıcı olarak başarısız işaretlenir, başka bekleme ve 7. bir deneme yoktur.

Yeniden Denenebilir ile Yeniden DenenemezBölüm bağlantısını kopyala

Yeniden denenebilir yanıtlarBölüm bağlantısını kopyala

Bu durum kodları otomatik yeniden denemeyi tetikler:

• 408 Request Timeout
• 429 Too Many Requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout
• Ağ hataları (zaman aşımı, soket hataları, DNS hataları)

Yeniden denenemez yanıtlarBölüm bağlantısını kopyala

Bu durum kodları kalıcı hata olarak kabul edilir, yeniden deneme yapılmaz:

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• Diğer tüm 4xx hataları (408 ve 429 hariç)
• Doğrulamayı geçemeyen bir yönlendirme yanıtı (bkz. Yönlendirmeler) veya sıçrama sınırını aşan bir yönlendirme

YönlendirmelerBölüm bağlantısını kopyala

MailLand uç noktanızı bir tarayıcı gibi ele almaz. Yönlendirmeler elle takip edilir, en fazla 3 sıçrama, ve her sıçramaya bir şey gönderilmeden önce yeniden doğrulanır:

• hedef https:// olmalıdır: http:// adresine bir yönlendirme reddedilir, düşürülmez;
• hedef genel bir adrese çözümlenmelidir: özel, loopback veya link-local bir adrese yönlendirme reddedilir ve istek hiçbir zaman gönderilmez;
• 3 sıçramayı aşmak teslimatı başarısız kılar.

Reddedilen bir yönlendirme, durum kodu olmadan bir teslimat hatası olarak bildirilir. Uç noktanız taşındıysa, bir yönlendirmeye güvenmek yerine webhook'u yeni URL'ye yönlendirin.

Teslim YapılandırmasıBölüm bağlantısını kopyala

Gelen Kutusu TeslimatlarıBölüm bağlantısını kopyala

inbound.received, diğer tüm olaylarla aynı durable dispatcher tarafından; yukarıda anlatılan aynı yeniden deneme planı, aynı Retry-After işleyişi, aynı teslimat geçmişi ve aynı otomatik duraklatma ile teslim edilir.

• Diğer olaylarda olduğu gibi event_id (X-MLND-Event-Id ile aynı) üzerinden yinelenenleri kaldırın. Bu kimlik her gelen ileti ve webhook için sabittir; aynı e-posta için her deneme aynı kimliği taşır.
• Elle yeniden oynatma yeni bir olaydır: yeni bir event_id alır, özgün kimlik data.replay_of içindedir. data.idempotency_key aynı kalır.
• Her ekin download_url değeri her denemede imzalanır ve o andan itibaren 15 dakika geçerlidir; ekin id değeri her denemede aynıdır. Bkz. Gelen Posta Webhook'ları.

Teslim Geçmişini GörüntülemeBölüm bağlantısını kopyala

Bir webhook için geçmiş teslimatları görün:

GET https://api.mail.land/v1/webhooks/{id}/deliveries

curl -X GET "https://api.mail.land/v1/webhooks/wh_abc123/deliveries?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Sorgu ParametreleriBölüm bağlantısını kopyala

{
  "items": [
    {
      "publicId": "p8r2kx7m9wq4rtz",
      "eventType": "message.delivered",
      "messageId": "t_a1b2c3d4e5f6",
      "statusCode": 200,
      "responseTimeMs": 145,
      "success": true,
      "errorMessage": null,
      "createdAt": "2026-02-17T12:34:58.000Z",
      "attemptNumber": 1
    },
    {
      "publicId": "p8r2kx7m3nq1abc",
      "eventType": "message.bounced",
      "messageId": "t_d4e5f6a1b2c3",
      "statusCode": 503,
      "responseTimeMs": 15000,
      "success": false,
      "errorMessage": "Service Unavailable",
      "createdAt": "2026-02-17T12:30:00.000Z",
      "attemptNumber": 3
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Başarısız Teslimatı Yeniden DeneBölüm bağlantısını kopyala

Belirli bir başarısız teslimatı elle yeniden deneyin:

POST https://api.mail.land/v1/webhooks/{id}/deliveries/{publicId}/retry

curl -X POST https://api.mail.land/v1/webhooks/wh_abc123/deliveries/p8r2kx7m3nq1abc/retry \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Başarı durumunda 202 Accepted döner. Yeniden deneme kuyruğa alınır ve orijinal olay verisini kullanır.

Hatalarda Otomatik DuraklatmaBölüm bağlantısını kopyala

Bir webhook yeterince ardışık başarısız teslim denemesi biriktirdiğinde, MailLand onu otomatik olarak duraklatır. Eşik değeri, 0'dan büyük bir değere ayarlanmışsa webhook'un kendi pauseThreshold değeridir, aksi halde varsayılan değer olan 10 ardışık başarısız teslim denemesidir:

1. Webhook'un isActive değeri false olarak ayarlanır ve pausedAt / pausedReason doldurulur: pausedReason kaç hata olduğunu ve sonuncusunun ne olduğunu söyler
2. Uygulama içi bir bildirim oluşturulur
3. Webhook yeniden başlatılana kadar başka olay teslim edilmez

Sayaç denemelerin sayacıdır, olayların değil: tüm yeniden deneme merdivenini tüketen tek bir olay birden fazla hataya katkıda bulunur.

Eşiğe ulaşılmadan önce erken bir uyarı bildirimi yoktur: bildirilmeyi beklemek yerine consecutiveFailures alanını proaktif olarak kontrol edin (aşağıdaki En İyi Uygulamalar'a bakın).

Duraklatılmış Webhook'u Yeniden BaşlatBölüm bağlantısını kopyala

POST https://api.mail.land/v1/webhooks/{id}/resume

curl -X POST https://api.mail.land/v1/webhooks/wh_abc123/resume \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Bu işlem webhook'u yeniden etkinleştirir: duraklama durumunu temizler, ardışık hata sayacını sıfırlar ve tekrar etkin yapar. Sonraki olay teslimi normal şekilde denenir.

En İyi UygulamalarBölüm bağlantısını kopyala

• 200'ü hızlı döndürün: webhook verilerini zaman uyumsuz olarak işleyin. Olayı kuyruğa alın ve hemen 200 döndürün. Uzun süren işleyiciler zaman aşımı riskini artırır.
• Idempotent işleme için olay kimliğini kullanın: X-MLND-Event-Id başlığı (ve payload'daki karşılık gelen event_id alanı), yeniden denemeler ve yeniden gönderimler boyunca sabittir: aynı temel olay, kaç kez yeniden teslim edilirse edilsin her zaman aynı kimlikle gelir. İşlenmiş kimlikleri saklayın ve daha önce işlediklerinizi atlayın, böylece yinelenen bir teslimat sizin tarafınızda hiçbir şey yapmaz.
• Ardışık hataları izleyin: webhook'ları listelerken consecutiveFailures alanını kontrol edin. Otomatik duraklama eşiğine ulaşmadan önce araştırın.
• 429'u düzgün işleyin: uç noktanız aşırı yüklendiyse, Retry-After başlığıyla 429 döndürün. MailLand buna uyacaktır.

Sonraki AdımlarBölüm bağlantısını kopyala

• İmza Doğrulama: webhook özgünlüğünü doğrulayın
• Olaylar: tam olay türü başvurusu
• Webhook'lara Genel Bakış: webhook'ları oluşturun ve yönetin