Kullanıcı Ekleme Webhook'u (Users Webhook)

Kendi web sitenizi Mailinu'ya bağlayarak, sitenize üye olan / form dolduran kişileri anında ve güvenli şekilde alıcı listenize ekleyebilirsiniz. Her yeni kayıt geldiğinde adres arka planda doğrulanır, tekrarlar tekilleştirilir ve seçtiğiniz kampanyalara eklenir.

1. Nasıl Çalışır?

Sitenizin sunucusu, her yeni kişi için bize tek bir istek gönderir. İsteği alınca kaydı doğrulama kuyruğuna alırız; geçerliyse listenizde görünür, geçersizse hata listesinde kalır.

2. Kurulum

• Kullanıcılar → Webhook ekranını açın.
• Hedef proje ve kampanya(lar)ı seçin.
• İsteğe bağlı: gelen kayıtta dil yoksa uygulanacak varsayılan dil ve İYS onaylarını kabul et seçeneği.
• Aktifleştir deyin; size özel bir URL ve gizli anahtar (secret) verilir.

🔒 Secret gizlidir; yalnızca sunucunuzda saklayın, tarayıcıya/istemciye koymayın. Sızarsa Secret'i Yenile ile tek tıkla değiştirin (URL değişmez).

Ayarlar — hangi alan ne işe yarar?

• Proje (zorunlu) ve Kampanyalar: Gelen kişilerin ekleneceği yer. Kampanya seçmezseniz projenin varsayılan (General) kampanyasına eklenir.
• Varsayılan dil: Gelen istekte lang yoksa bu dil uygulanır (boş bırakılabilir).
• İstek koruması (otomatik): Sitenizden gelen istekleri ani sel/hatalı döngüye karşı Mailinu otomatik sınırlar; bu bir ayar değildir, sizin bir şey yapmanıza gerek yoktur. Çok yüksek hacim beklentiniz varsa bize bildirin.
• Webhook aktif: Kapalıyken gelen tüm istekler reddedilir (403). Açabilmek için önce proje seçili olmalıdır.
• İYS onaylarını kabul et: Açıksa, istekte gönderdiğiniz iys_email/iys_sms/iys_arama onayları kaydedilir; kapalıysa yok sayılır. İYS ürününüz varsa bu seçenek açıkken iys_email: true gönderdiğiniz kişiler ayrıca İYS'ye otomatik ONAY olarak kaydedilir — aşağıdaki 6. İYS'ye Otomatik İzin Kaydı başlığına bakın.
• Secret'ı Yenile: Gizli anahtarı değiştirir; adres (URL) aynı kalır, eski secret geçersiz olur.

3. İstek (Örnek)

Her yeni kişi için sunucunuzdan şu isteği gönderin:

curl -X POST "https://api-customer.mailinu.com/app/user/webhook/<WEBHOOK_ID>/users" \
  -H "Authorization: Bearer <SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ali","surname":"Veli","email":"ali@ornek.com","lang":"tr"}'

Alanlar: email (zorunlu), name, surname, lang (dil kodu ya da adı; boş olabilir). İYS kabulü açıksa iys_email, iys_sms, iys_arama (true/false) da gönderebilirsiniz.

4. Yanıtlar

• 202 queued — kayıt alındı, doğrulanıyor.
• 200 duplicate — bu e-posta ilgili kampanyalarda zaten var.
• 400 — geçersiz e-posta veya eksik yapılandırma.
• 401 — secret hatalı · 403 — webhook kapalı · 429 — hız limiti (kısa süre sonra tekrar deneyin).

5. Güvenlik ve Limitler

• Tüm istekler HTTPS üzerinden ve secret ile kimliklenir.
• Hız koruması otomatiktir (yaklaşık dakikada 120 istek) ve bir ayar değildir. Çok yüksek hacim beklentiniz varsa bize bildirin.
• Kayıtlar tek tek gönderilir (her kişi ayrı istek). Büyük listeler için CSV ile toplu yüklemeyi kullanın.

6. İYS'ye Otomatik İzin Kaydı (İYS ürününüz varsa)

Hesabınızda İYS ürünü tanımlıysa ve İYS onaylarını kabul et seçeneği açıksa, webhook ile "iys_email": true gönderdiğiniz kişiler otomatik olarak İYS'ye ONAY kaydı olarak işlenir. Böylece siteniz üzerinden izin veren kişiler için ayrıca İYS'ye Ekle yapmanıza gerek kalmaz; kişi Kullanıcılar ekranında doğrudan Onaylı rozetiyle görünür.

• true → kişi hem Mailinu'da hem İYS'de onaylı olur. İzin tarihi olarak kaydın bize ulaştığı an, kaynak olarak HS_WEB yazılır.
• false ya da alanı hiç göndermemek → hiçbir şey yazılmaz. Bu ret anlamına gelmez; kişi İYS tarafında Bilinmiyor kalır.
• Hâlihazırda İYS'de onaylı olan kişi için tekrar kayıt oluşturulmaz.
• İYS ürününüz yoksa veya İYS onaylarını kabul et kapalıysa bu köprü hiç çalışmaz — onay yalnızca Mailinu içinde tutulur, İYS'ye yazılmaz.
• İşlem arka planda yürür: webhook yanıtınız (202) gecikmez. İYS'ye yazma başarısız olursa kişi Mailinu'da da onaylı görünmez — yani gerçekte olmayan bir onay asla oluşmaz.

⚠️ Önemli: iys_email: true göndermek, o kişinin ticari elektronik ileti onayını gerçekten verdiğini beyan etmek demektir ve bu beyan ulusal İYS kaydına işlenir. Bu alanı yalnızca sitenizde açık bir onay kutusu işaretlenmişse true gönderin.

💡 Gelen adresler de normal doğrulamadan geçer; geçersiz/riskli adresler eklenmez, listenizin kalitesi korunur. İYS yükümlülükleri size aittir — yalnızca onay verdiğiniz kişilere gönderim yapın.