Webhook Olayları

MailLand'in olay kataloğu, 6 kategoride 21 olay türü tanımlar (bu 21 türden 2'si abone olamayacağınız platform bildirimleridir). Her olay, webhook uç noktanıza imzalı bir HTTP POST isteği olarak teslim edilir.

Olay KataloğuBölüm bağlantısını kopyala

Tam olay kataloğunu programatik olarak alın:

GET https://api.mail.land/v1/webhooks/catalog

curl -X GET https://api.mail.land/v1/webhooks/catalog

{
  "version": 1,
  "products": [
    { "id": "transactional", "name": "Transactional Email", "isActive": true, "comingSoon": false },
    { "id": "marketing", "name": "Marketing Email", "isActive": true, "comingSoon": false },
    { "id": "inbound", "name": "Inbound Email", "isActive": true, "comingSoon": false },
    { "id": "system", "name": "System Events", "isActive": true, "comingSoon": false },
    { "id": "validation", "name": "Email Validation", "isActive": false, "comingSoon": true }
  ],
  "categories": [
    {
      "id": "message",
      "name": "Message Events",
      "events": [
        { "id": "message.sent", "name": "Message Sent", "products": ["transactional", "marketing"] },
        { "id": "message.delivered", "name": "Message Delivered", "products": ["transactional", "marketing"] }
      ]
    }
  ]
}

Bu uç nokta herkese açıktır (kimlik doğrulama gerekmez) ve her zaman en güncel katalog sürümünü döner.

Standart Veri YapısıBölüm bağlantısını kopyala

Her webhook teslimatı tutarlı bir dış yapı içerir:

{
  "event": "message.delivered",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "timestamp": "2026-02-17T12:34:56.789Z",
  "occurred_at": "2026-02-17T12:34:56.120Z",
  "schema_version": 1,
  "data": {
    // Event-specific fields
  }
}

Her mesaj olayının data alanı ayrıca status_version, status, previous_status, complaint_status ve reason içerir, bkz. Durum sürümleri.

Durum sürümleriBölüm bağlantısını kopyala

Her mesaj olayı data.status_version, data.status, data.previous_status, data.complaint_status ve data.reason içerir. MailLand, mesajın durumunda, nedeninde veya şikâyet durumunda bir değişiklik için her olay gönderdiğinde status_version bir artar.

İki istisna:

• Bir mesaj queued veya sent iken status_version 0 ile başlar. queued durumundan sent durumuna geçiş olay göndermez ve sürümü değiştirmez.
• Birden çok message.deferred olayı aynı status_version değerini paylaşabilir: tekrarlanan bir gecikme durumu değiştirmez.

Webhook'lar sırasız gelebilir ve yeniden denenebilir; bu yüzden onları varış sırasına göre değil, her zaman status_version değerine göre uygulayın.

Bir durum, kesinleştikten sonra değişebilir. MailLand bildiğini bildiği anda raporlar. Sonradan daha fazlasını öğrenirse yeni durumu daha yüksek bir status_version ile gönderir:

• teslim edilmiş bir mesaj, alıcının sunucusu onu sonradan reddettiğinde geri dönebilir (bant dışı geri dönüş);
• bir iç arızadan sonra veya MailLand'in posta sunucusu toparlandıktan sonra bir teslim ya da ret geç bildirilebilir. Bu durumda failed bir mesaj bounced veya delivered olabilir, bounced bir mesaj delivered olabilir ve unknown bir mesaj herhangi bir son duruma geçebilir.

Bir mesaj asla delivered durumundan failed durumuna geçmez. MailLand bu düzeltmeleri sayar.

Yeniden deneme süreleriBölüm bağlantısını kopyala

MailLand ertelenen bir mesajı yeniden deneme süresi dolana kadar yeniden dener: işlemsel postada, teslim kuyruğuna ilk verildikten yaklaşık 5 saat sonrasına, pazarlama postasında yaklaşık 25 saat sonrasına kadar. Süre dolduktan sonra MailLand mesajı yeni bir teslim denemesi için kuyruğa almaz. Süre dolduğunda zaten bir bağlantı bekleyen bir kopya bundan sonra da denenebilir. Bunlar yeniden deneme süreleridir, son olayı ne zaman alacağınıza dair söz değildir. Her olayı, sonuç MailLand'e ulaştığında alırsınız; bu gecikme henüz ölçülmedi ve bir iç kesinti sırasında daha uzun olabilir. MailLand'in 24 saat içinde teslim kuyruğuna veremediği bir mesaj expired olarak sonlandırılır.

Bir mesajın güncel durumunu webhook'lardan tutuyorsanız (işlem gerekli)Bölüm bağlantısını kopyala

Bu, mevcut entegrasyonlar için bir davranış değişikliğidir. message.failed veya message.delivered olayını kalıcı sayan ve sonraki olayları yok sayan bir entegrasyon, bir düzeltmeden sonra yanlış bir durumda kalabilir. Zaten var olan olay adlarının artık yeni olası sıraları vardır.

• Her mesaj olayına abone olun: message.delivered, message.deferred, message.bounced, message.failed, message.complained, message.outcome_unknown ve message.retried. Ancak o zaman aldığınız olaylar her durum değişikliğini içerir.
• status_version değerini durumla birlikte saklayın. Bir olayı yalnızca status_version değeri sakladığınızdan yüksekse uygulayın; aynı sürümlü bir message.deferred hiçbir şeyi değiştirmez.
• message.failed, message.bounced veya message.delivered sonrasında da olayları işlemeye devam edin: daha yüksek status_version taşıyan sonraki bir olay önceki durumun yerini alır.
• API'nin status_version değerine kadar her olayı aldığınızda durumunuz API'ninkine eşittir. API, o ana kadar aldığınız webhook'lardan ileride olabilir ve status_version 0 iken olay olmadan sent gösterebilir.

Yalnızca bazı mesaj olaylarına abone iseniz, aldığınız en yüksek status_version güncel durum olmayabilir: abone olmadığınız bir olay türü durumu değiştirmiş olabilir. Güncel durumu API'den okuyun (örneğin son aldığınız olayı message.failed, message.bounced veya message.outcome_unknown olan her mesaj için) ve uzlaştırın.

Entegrasyonunuzu değiştiremiyorsanız, önemsediğiniz mesajların durumunu API'den sorgulayın. Yalnızca olay sayan veya yalnızca geçmiş gösteren entegrasyonların bir değişikliğe ihtiyacı yoktur.

Mesaj OlaylarıBölüm bağlantısını kopyala

message.sentBölüm bağlantısını kopyala

Örnektir: henüz yayınlanmıyor. Bu olay katalogda var ama bugün için bir üreteci yok.

{
  "event": "message.sent",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "timestamp": "2026-02-17T12:34:56.789Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:34:56.789Z"
  }
}

message.deliveredBölüm bağlantısını kopyala

E-posta, alıcının posta sunucusuna başarıyla teslim edildiğinde tetiklenir.

Bu olay, aynı mesaj için daha önceki bir son durumdan sonra bir düzeltme olarak da gelebilir. Bkz. Durum sürümleri.

{
  "event": "message.delivered",
  "event_id": "evt_b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "timestamp": "2026-02-17T12:34:58.123Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:34:58.123Z",
    "smtp_response": "OK",
    "status_version": 1,
    "status": "delivered",
    "previous_status": "sent",
    "complaint_status": "none",
    "reason": null
  }
}

message.deferredBölüm bağlantısını kopyala

Teslimat geçici olarak ertelendiğinde tetiklenir. MailLand otomatik olarak yeniden dener.

Bir mesaj birkaç kez ertelenebilir. İlk erteleme status_version değerini artırır; tekrarlanan ertelemeler aynı status_version değerini taşır.

{
  "event": "message.deferred",
  "event_id": "evt_c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
  "timestamp": "2026-02-17T12:35:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:35:00.000Z",
    "smtp_response": "Try again later",
    "bounce_reason": "TransientFailure"
  }
}

message.bouncedBölüm bağlantısını kopyala

Bir e-posta geri döndüğünde (kalıcı veya geçici) tetiklenir.

Bu olay, aynı mesaj için daha önceki bir son durumdan sonra bir düzeltme olarak da gelebilir. Bkz. Durum sürümleri.

{
  "event": "message.bounced",
  "event_id": "evt_d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
  "timestamp": "2026-02-17T12:35:01.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:35:01.000Z",
    "bounce_type": "hard",
    "bounce_reason": "InvalidRecipient",
    "smtp_response": "The email account that you tried to reach does not exist.",
    "status_version": 1,
    "status": "bounced",
    "previous_status": "sent",
    "complaint_status": "none",
    "reason": "InvalidRecipient"
  }
}

bounce_reason, MailLand'in bounce'a atadığı sınıflandırma belirtecidir (ör. InvalidRecipient, QuotaIssues, SpamBlock), ham SMTP metni değildir, bunun için smtp_response kullanın. bounce_type, hard, soft, blocked veya unknown değerlerinden biridir.

smtp_response, alıcı sunucunun yanıt metnidir; sayısal yanıt kodunu ve genişletilmiş durum kodunu içermez. bounce_type, MailLand'in adresle ne yaptığını söyler: hard, tüm e-postalar için engellendi; soft, pazarlama e-postaları için 30 gün engellendi; blocked, ret adresle değil gönderimle ilgiliydi (örneğin spam filtresi, gönderen kimlik doğrulaması, itibar veya alıcının politikası), bu yüzden hiçbir şey engellenmez; unknown, sınıflandırma yok, soft gibi işlenir.

message.failedBölüm bağlantısını kopyala

MailLand bir mesajı, teslim edilmediğine dair kesin kanıta dayanarak, alıcıdan değil MailLand tarafından kaynaklanan bir nedenle sonlandırdığında tetiklenir. Durum sürümleri altında anlatılan durumlarda, ardından daha yüksek bir status_version ile message.delivered veya message.bounced gelebilir. Mesajın durumu Bounced değil Failed olur ve reason durumu belirtir:

• Alıcı engellenmez ve bu hata geri dönüş oranınıza sayılmaz.
• Bir mesaj en fazla bir message.failed üretir. MailLand daha sonra bir teslim veya ret almadıkça bu, o mesajın son olayıdır; alırsa daha yüksek bir status_version ile message.delivered veya message.bounced gelir.

Alıcı posta sunucusunun reddi message.bounced olarak bildirilir, asla message.failed olarak değil.

{
  "event": "message.failed",
  "event_id": "evt_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "timestamp": "2026-09-28T02:00:19.1047332Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-09-28T02:00:18.2522997Z",
    "reason": "dkim_revoked",
    "smtp_response": "Next delivery time PT3.028008S > PT1S",
    "status_version": 1,
    "status": "failed",
    "previous_status": "sent",
    "complaint_status": "none"
  }
}

message.outcome_unknownBölüm bağlantısını kopyala

MailLand bir mesajın teslim kuyruğuna ulaşıp ulaşmadığını belirleyemediğinde tetiklenir; örneğin teslim kesintiye uğradığı ve sonradan doğrulanamadığı için. Mesajın yeniden deneme süresinden bir süre sonra, şu an 7 gün, o zamana kadar hiçbir kanıt gelmemişse gönderilir. Bu bir son durum değildir. Durum unknown olur. MailLand sonucu daha sonra öğrenirse, daha yüksek bir status_version ile message.delivered, message.bounced veya message.failed alırsınız.

{
  "event": "message.outcome_unknown",
  "event_id": "evt_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
  "timestamp": "2026-10-08T17:05:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-10-08T17:05:00.000Z",
    "status_version": 1,
    "status": "unknown",
    "previous_status": "queued",
    "complaint_status": "none",
    "reason": "handoff_undetermined"
  }
}

message.retriedBölüm bağlantısını kopyala

Geri dönen veya başarısız bir mesajı yeniden denediğinizde ve MailLand onu tekrar kuyruğa aldığında tetiklenir. Durum queued olur ve status_version artar; yeniden gönderilen kopyanın olayları daha yüksek sürümlerle gelir. Bu bir son durum değildir.

{
  "event": "message.retried",
  "event_id": "evt_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
  "timestamp": "2026-10-01T18:00:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-10-01T18:00:00.000Z",
    "attempt": 1,
    "status_version": 2,
    "status": "queued",
    "previous_status": "bounced",
    "complaint_status": "none",
    "reason": null
  }
}

Etkileşim OlaylarıBölüm bağlantısını kopyala

message.openedBölüm bağlantısını kopyala

Örnektir: kullanılamıyor.

{
  "event": "message.opened",
  "event_id": "evt_f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "timestamp": "2026-02-17T13:15:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T13:15:00.000Z"
  }
}

message.clickedBölüm bağlantısını kopyala

Örnektir: kullanılamıyor.

{
  "event": "message.clicked",
  "event_id": "evt_g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1",
  "timestamp": "2026-02-17T13:16:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T13:16:00.000Z"
  }
}

message.unsubscribedBölüm bağlantısını kopyala

Bir alıcı gönderdiğiniz bir iletiden abonelikten çıktığında yayınlanır: iletinin List-Unsubscribe başlığı veya mailto: adresi, tek tıklamalı POST, abonelikten çıkma bağlantısı ya da tercih sayfası üzerinden. API veya panel üzerinden kendinizin yaptığı abonelik iptalleri ve spam şikayetleri (message.complained) için yayınlanmaz. İleti başına bir kez, alıcının çıkarıldığı anda, ona abone her uç noktaya gönderilir. Her ileti olayı gibi data ayrıca iletinin güncel durum alanlarını da taşır (Durum sürümleri bölümüne bakın).

{
  "event": "message.unsubscribed",
  "event_id": "evt_h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2",
  "timestamp": "2026-02-17T14:00:00.000Z",
  "data": {
    "message_id": "m_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T14:00:00.000Z",
    "status_version": 3,
    "status": "delivered",
    "previous_status": "queued",
    "complaint_status": "none",
    "reason": null
  }
}

Engelleme OlaylarıBölüm bağlantısını kopyala

message.complainedBölüm bağlantısını kopyala

Bir alıcı e-postayı spam olarak işaretlediğinde (ISP geri bildirim döngüsü) tetiklenir.

{
  "event": "message.complained",
  "event_id": "evt_i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3",
  "timestamp": "2026-02-17T15:00:00.000Z",
  "data": {
    "message_id": "m_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T15:00:00.000Z",
    "feedback_type": "abuse"
  }
}

suppression.addedBölüm bağlantısını kopyala

Örnektir: henüz yayınlanmıyor. Bu olay katalogda var ama bugün için bir üreteci yok.

{
  "event": "suppression.added",
  "event_id": "evt_j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4",
  "timestamp": "2026-02-17T15:00:01.000Z",
  "data": {
    "email": "[email protected]",
    "type": "complaint",
    "scope": "global",
    "reason": "Spam complaint via ISP feedback loop"
  }
}

suppression.removedBölüm bağlantısını kopyala

Örnektir: henüz yayınlanmıyor. Bu olay katalogda var ama bugün için bir üreteci yok.

{
  "event": "suppression.removed",
  "event_id": "evt_k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5",
  "timestamp": "2026-02-17T16:00:00.000Z",
  "data": {
    "email": "[email protected]",
    "type": "manual",
    "scope": "global"
  }
}

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

inbound.receivedBölüm bağlantısını kopyala

Alan adlarınızdan birine gelen bir e-posta alındığında tetiklenir.

{
  "event": "inbound.received",
  "event_id": "evt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "timestamp": "2026-02-17T12:00:00.000Z",
  "occurred_at": "2026-02-17T12:00:00.000Z",
  "schema_version": 1,
  "data": {
    "idempotency_key": "r7n2k5x9m1p4w6_s5m3x8k1p7n4w2",
    "email": {
      "id": "r7n2k5x9m1p4w6",
      "received_at": "2026-02-17T12:00:00.000Z",
      "size_bytes": 4521,
      "envelope": {
        "from": "[email protected]",
        "to": ["[email protected]"]
      },
      "headers": {
        "from": { "address": "[email protected]", "name": "Jane Doe" },
        "to": [{ "address": "[email protected]" }],
        "subject": "Help with my order",
        "message_id": "<[email protected]>",
        "date": "2026-02-17T11:59:50.000Z"
      },
      "body": {
        "text_preview": "Hi, I need help with...",
        "has_text": true,
        "has_html": true
      },
      "attachments": [],
      "authentication": {
        "spf": { "result": "pass" },
        "dkim": { "result": "pass" },
        "dmarc": { "result": "pass" }
      },
      "spam": {
        "score": 0.1,
        "is_spam": false,
        "reason": null
      },
      "source": {
        "ip": "203.0.113.10",
        "hostname": "mail.external.com"
      }
    },
    "matched_route": {
      "id": "s5m3x8k1p7n4w2",
      "name": "Support inbox"
    }
  }
}

Hesap OlaylarıBölüm bağlantısını kopyala

account.webhook_pausedBölüm bağlantısını kopyala

Bir webhook, ardışık hatalar nedeniyle otomatik olarak duraklatıldığında tetiklenir.

{
  "event": "account.webhook_paused",
  "event_id": "evt_m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7",
  "timestamp": "2026-02-17T18:00:00.000Z",
  "data": {
    "webhook_id": "z8m3p1k6x4w2n7",
    "webhook_name": "Production Events",
    "consecutive_failures": 10,
    "last_error": "Connection refused"
  }
}

account.domain_verifiedBölüm bağlantısını kopyala

Örnektir: henüz yayınlanmıyor. Bu olay katalogda var ama bugün için bir üreteci yok.

{
  "event": "account.domain_verified",
  "event_id": "evt_n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8",
  "timestamp": "2026-02-17T10:15:00.000Z",
  "data": {
    "domain_id": "q3z8v1k6m9p2x5",
    "domain": "yourdomain.com"
  }
}

account.domain_failedBölüm bağlantısını kopyala

Örnektir: henüz yayınlanmıyor. Bu olay katalogda var ama bugün için bir üreteci yok.

{
  "event": "account.domain_failed",
  "event_id": "evt_o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9",
  "timestamp": "2026-02-17T10:15:00.000Z",
  "data": {
    "domain_id": "q3z8v1k6m9p2x5",
    "domain": "yourdomain.com",
    "reason": "DKIM record not found for selector mlnd"
  }
}

account.quota_warningBölüm bağlantısını kopyala

Örnektir: henüz yayınlanmıyor. Bu olay katalogda var ama bugün için bir üreteci yok.

{
  "event": "account.quota_warning",
  "event_id": "evt_p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
  "timestamp": "2026-02-17T20:00:00.000Z",
  "data": {
    "used": 45000,
    "limit": 50000,
    "percentage": 90
  }
}

account.quota_exceededBölüm bağlantısını kopyala

Örnektir: henüz yayınlanmıyor. Bu olay katalogda var ama bugün için bir üreteci yok.

{
  "event": "account.quota_exceeded",
  "event_id": "evt_q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1",
  "timestamp": "2026-02-17T22:00:00.000Z",
  "data": {
    "used": 50000,
    "limit": 50000,
    "percentage": 100
  }
}

Olay ÖzetiBölüm bağlantısını kopyala

"Kullanılabilir", kataloğun availableNow bayrağıdır: bugün gerçekten bir şeyin olayı yayınlayıp yayınlamadığı. Yalnızca kullanılabilir olaylar bir aboneliğe dahil edilebilir.

Gelecekteki OlaylarBölüm bağlantısını kopyala

includeFutureEvents true olduğunda (varsayılan), abone olduğunuz ürünlere yeni olay türleri eklendikçe webhook'unuz bunları otomatik olarak alır. Aboneliğinizi mevcut olay anlık görüntüsüne kilitlemek için bunu false olarak ayarlayın.

Yukarıda "Henüz değil" olarak işaretlenen olaylar, üreticileri yayına girdiğinde abone olunabilir hale gelir: burada belgelenen olay adları ve veri yapıları bu gerçekleştiğinde değişmeyecektir.

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

• İmza Doğrulama: olayların MailLand'den geldiğini doğrulayın
• Yeniden Deneme Mantığı: yeniden deneme davranışını anlayın
• Webhook'lara Genel Bakış: webhook oluşturun ve yönetin