Webhook'lara Genel Bakış

Webhook'lar, e-posta olayları gerçekleştiğinde (teslimler, geri dönmeler, şikayetler ve daha fazlası) sunucunuza gerçek zamanlı HTTP bildirimleri iletir. Durum değişikliklerini sorgulamak yerine, MailLand olayları gerçekleştikleri anda endpoint'inize iletir.

Webhook'lar Nasıl ÇalışırBölüm bağlantısını kopyala

Webhook OluşturmaBölüm bağlantısını kopyala

POST https://api.mail.land/v1/webhooks

curl -X POST https://api.mail.land/v1/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "includeFutureEvents": true,
    "scope": "all_domains"
  }'

İstek AlanlarıBölüm bağlantısını kopyala

YanıtBölüm bağlantısını kopyala

Durum: 201 Created

{
  "webhook": {
    "id": "k3m9x2p7qw4rtz",
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "includeFutureEvents": true,
    "scope": "all_domains",
    "domainIds": [],
    "isActive": true,
    "createdAt": "2026-02-17T10:00:00Z",
    "successCount": 0,
    "failureCount": 0,
    "consecutiveFailures": 0,
    "pauseThreshold": 10
  },
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0..."
}

Webhook'ları ListeleBölüm bağlantısını kopyala

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

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

[
  {
    "id": "k3m9x2p7qw4rtz",
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced"],
    "isActive": true,
    "lastTriggeredAt": "2026-02-17T12:30:00Z",
    "lastSuccessAt": "2026-02-17T12:30:00Z",
    "successCount": 1542,
    "failureCount": 3,
    "consecutiveFailures": 0,
    "createdAt": "2026-02-10T08:00:00Z"
  }
]

Oluşturma tarihine göre sıralanmış (en yenisi önce) en fazla 100 webhook döndürür.

Webhook Detayını GörüntüleBölüm bağlantısını kopyala

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

curl -X GET https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

En son 50 teslimat kaydıyla birlikte tam webhook yapılandırmasını döndürür. Teslimat kaydı ayrıntıları için Yeniden Deneme Mantığı sayfasına bakın.

Webhook GüncellemeBölüm bağlantısını kopyala

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

curl -X PUT https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "All Events",
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "isActive": true
  }'

Tüm alanlar isteğe bağlıdır: yalnızca değiştirmek istediğiniz alanları ekleyin.

Webhook Test EtmeBölüm bağlantısını kopyala

Endpoint'inizin çalıştığını doğrulamak için bir test olayı gönderin:

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

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

{
  "success": true,
  "statusCode": 200,
  "statusText": "OK",
  "durationMs": 145,
  "responseBody": "{\"received\": true}",
  "headersSent": {
    "X-MLND-Signature": "t=1708171200,v1=abc123...",
    "X-MLND-Event-Id": "evt_test_abc123",
    "X-MLND-Event-Version": "1",
    "X-MLND-Event": "webhook.test",
    "X-MLND-Webhook-Id": "k3m9x2p7qw4rtz",
    "X-MLND-Attempt": "1"
  },
  "wouldReceiveRealEvents": true,
  "liveEvents": ["message.delivered", "message.bounced"],
  "dormantEvents": {},
  "subscriptionWarning": null
}

Test gönderimi gerçek bir olayla aynı imzalamayı ve aynı teslim taşımasını kullanır; bu nedenle burada başarı, URL'nizi, TLS'nizi ve imza doğrulamanızı kanıtlar.

Aboneliğinizi kanıtlamaz: test isteğe bağlı olarak gönderilir, olay seçiminize göre yönlendirilmez. Son dört alan bunu ayrıca yanıtlar:

"success": true ile birlikte "wouldReceiveRealEvents": false önemli durumdur: uç nokta çalışıyor ama teslim edilebilecek hiçbir şeye abone değil.

Test başarısız olursa errorType alanı nedeni gösterir: ssrf_blocked (URL'nin veya ondan yapılan bir yönlendirmenin, platformun göndermeyi reddettiği bir yeri göstermesi) veya network_error (zaman aşımı, TLS hatası, bağlantı reddi; ayrıntıyı errorMessage taşır).

Secret YenilemeBölüm bağlantısını kopyala

Webhook secret'ınızı kaybettiyseniz veya döndürmeniz gerekiyorsa:

POST https://api.mail.land/v1/webhooks/{id}/regenerate-secret

curl -X POST https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz/regenerate-secret \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "secretKey": "whsec_x9y8z7w6v5u4..."
}

Domain KapsamıBölüm bağlantısını kopyala

Varsayılan olarak, webhook'lar çalışma alanınızdaki tüm domainler için olayları alır. Bir webhook'u belirli domainlerle sınırlamak için:

{
  "webhookUrl": "https://your-app.com/webhooks/mailland",
  "scope": "selected_domains",
  "domainIds": ["d4n8q1zt5wm3xc", "b7r2mv9k0jy4pw"]
}

Yalnızca bu domainlerle ilgili olaylar webhook'u tetikler.

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

MailLand, 10 ardışık teslimat hatası (webhook başına pauseThreshold aracılığıyla yapılandırılabilir) sonrasında webhook'ları otomatik olarak duraklatır. Bu, çevrimdışı endpoint'ler için kaynak israfını önler.

Bir webhook duraklatıldığında:

• pausedAt zaman damgası ayarlanır
• pausedReason neden duraklatıldığını açıklar
• Diğer aktif webhook'larınıza bir account.webhook_paused olayı gönderilir
• Uygulama içi bir bildirim oluşturulur

Duraklatılmış Webhook'u SürdürmeBölüm bağlantısını kopyala

Sorunu düzelttikten sonra teslimatı sürdürün:

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

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

Bu işlem duraklatma durumunu temizler, ardışık hata sayacını sıfırlar ve webhook'u yeniden etkinleştirir (isActive tekrar true olur), böylece gelecekteki olaylar ona normal şekilde teslim edilir.

Webhook SilmeBölüm bağlantısını kopyala

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

curl -X DELETE https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

204 No Content döndürür. Webhook, gelen e-posta rotaları tarafından kullanılıyorsa, bu rotalar otomatik olarak güncellenir veya devre dışı bırakılır.

Hata YanıtlarıBölüm bağlantısını kopyala

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

• Olaylar: tüm olay türlerinin ve verilerinin tam referansı
• İmza Doğrulama: webhook özgünlüğünü doğrulayın
• Yeniden Deneme Mantığı: yeniden deneme davranışını ve hata yönetimini anlayın