ShieldMail API ile Disposable Email Tespiti: Kapsamlı Kullanım Rehberi

Web sitenize kayıt olan kullanıcıların büyük bir kısmı gerçek email adresleri yerine tempmail.com, guerrillamail.com gibi geçici email servislerini mi kullanıyor? Sahte hesaplar, spam kayıtlar ve doğrulanamayan kullanıcılar veritabanınızı şişirirken gerçek kullanıcı istatistiklerinizi de bozuyor olabilir.

ShieldMail API, 194.000'den fazla disposable email domain'ini anlık olarak tespit eden, Türk geliştiriciler tarafından geliştirilen güçlü bir API servisidir. Bu rehberde, ShieldMail API'yi projelerinize nasıl entegre edeceğinizi adım adım anlatacağız.

ShieldMail API Nedir?

ShieldMail API, bir email adresinin veya domain'in disposable (tek kullanımlık) olup olmadığını kontrol eden RESTful bir servistir. 22'den fazla kaynaktan sürekli güncellenen veritabanı sayesinde yeni ortaya çıkan geçici email servislerini de hızla tespit eder.

API'nin sunduğu temel özellikler:

• Tek ve toplu email kontrolü — Tek bir email veya yüzlerce email'i aynı anda kontrol edebilirsiniz
• Önbellek sistemi — Sık sorgulanan domain'ler cache'lenerek yanıt süresi düşürülür
• Detaylı kullanım istatistikleri — Saatlik, günlük, haftalık ve aylık kullanımınızı takip edebilirsiniz
• Webhook desteği — Limit aşıldığında anında bildirim alabilirsiniz
• 14 programlama dili desteği — PHP, JavaScript, Python, C#, Java, Go, Ruby, Swift, Kotlin, Rust ve daha fazlası

Başlamadan Önce: Hesap Oluşturma ve Kurulum

Adım 1: Ücretsiz Hesap Oluşturun

https://api.teknikzeka.net/tempmail/user/?page=register adresine giderek ücretsiz hesabınızı oluşturun. Kayıt işlemi tamamlandığında size otomatik olarak bir API Key atanacaktır. Bu key, tüm API isteklerinizde kimlik doğrulama için kullanılır.

Adım 2: Domain Tanımlayın (Zorunlu)

Bu adım çok önemlidir ve atlanmamalıdır. ShieldMail API, güvenlik nedeniyle sadece tanımlı domain'lerden gelen istekleri kabul eder. Kullanıcı panelindeki "Domainler" sekmesinden API'yi kullanacağınız web sitenizin domain'ini eklemeniz gerekmektedir.

Örneğin, www.orneksite.com üzerinde kullanacaksanız bu domain'i panelden tanımlayın. Domain eklenmeden yapılan API istekleri NO_DOMAIN_DEFINED hatası döndürecektir.

Not: Postman, cURL gibi araçlarla test ederken referer header'ı gönderilmediği için domain kontrolü devre dışı kalır ve doğrudan test yapabilirsiniz.

Adım 3: Plan Seçimi

ShieldMail API, farklı ihtiyaçlara yönelik esnek planlar sunmaktadır:

Planlar haftalık, aylık veya yıllık olarak satın alınabilir. Yıllık planlarda önemli tasarruflar sağlanmaktadır. Ücretsiz plan, küçük projeler ve test amaçlı kullanım için yeterlidir.

API Kullanımı: Temel İşlemler

Kimlik Doğrulama

Tüm API isteklerinde kimlik doğrulama için API Key gönderilmelidir. İki yöntem desteklenir:

1. HTTP Header (Önerilen):

X-API-Key: sm_YOUR_API_KEY_HERE

2. Query Parametresi:

?key=sm_YOUR_API_KEY_HERE

Güvenlik açısından header yöntemi önerilir, çünkü query parametreleri sunucu loglarında görünür kalabilir.

Tek Email Kontrolü

En temel kullanım senaryosu, bir email adresinin disposable olup olmadığını kontrol etmektir:

GET https://api.teknikzeka.net/tempmail/api/?action=check&email=test@tempmail.com
Header: X-API-Key: sm_YOUR_API_KEY_HERE

Başarılı yanıt (engelli email):

{
  "success": true,
  "data": {
    "domain": "tempmail.com",
    "blocked": true,
    "disposable": true,
    "cached": false
  },
  "usage": {
    "hourly": "5/50",
    "daily": "12/500",
    "weekly": "45/2000",
    "monthly": "180/5000"
  }
}

Başarılı yanıt (temiz email):

{
  "success": true,
  "data": {
    "domain": "gmail.com",
    "blocked": false,
    "disposable": false,
    "cached": true
  },
  "usage": {
    "hourly": "6/50",
    "daily": "13/500"
  }
}

Yanıttaki önemli alanlar:

• blocked — Domain engelli listesinde mi? (true/false)
• disposable — Disposable email servisi mi?
• cached — Sonuç önbellekten mi geldi?
• usage — Mevcut kullanım durumunuz

Toplu Email Kontrolü

Birden fazla email'i tek istekte kontrol etmek için bulk_check endpoint'ini kullanabilirsiniz. Bu özellik, veritabanınızdaki mevcut kullanıcıları taramak veya toplu içe aktarma sırasında filtreleme yapmak için idealdir.

POST https://api.teknikzeka.net/tempmail/api/?action=bulk_check
Header: X-API-Key: sm_YOUR_API_KEY_HERE
Header: Content-Type: application/json

{
  "emails": [
    "user@tempmail.com",
    "contact@gmail.com",
    "info@guerrillamail.com"
  ]
}

Yanıt:

{
  "success": true,
  "data": [
    {
      "email": "user@tempmail.com",
      "domain": "tempmail.com",
      "blocked": true,
      "disposable": true
    },
    {
      "email": "contact@gmail.com",
      "domain": "gmail.com",
      "blocked": false,
      "disposable": false
    },
    {
      "email": "info@guerrillamail.com",
      "domain": "guerrillamail.com",
      "blocked": true,
      "disposable": true
    }
  ],
  "total": 3,
  "blocked_count": 2
}

Kullanım İstatistikleri

Mevcut planınızın limitlerini ve ne kadar kullandığınızı görmek için:

GET https://api.teknikzeka.net/tempmail/api/?action=usage

Bu endpoint; plan bilgilerinizi, limitlerinizi, mevcut kullanımınızı ve kalan hakkınızı detaylı olarak döndürür.

Gerçek Dünya Entegrasyon Örnekleri

Kayıt Formunda Kullanım (PHP)

En yaygın kullanım senaryosu, kullanıcı kayıt formlarında disposable email'leri engellemektir:

<?php
function isDisposableEmail(string $email): bool {
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => 'https://api.teknikzeka.net/tempmail/api/?action=check&email=' . urlencode($email),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 5,
        CURLOPT_HTTPHEADER => ['X-API-Key: API_KEYINIZ'],
    ]);
    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return ($res['success'] ?? false) && ($res['data']['blocked'] ?? false);
}

// Kayıt formunda kullanım
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $email = trim($_POST['email']);

    if (isDisposableEmail($email)) {
        $hata = 'Geçici email adresleri kabul edilmemektedir. Lütfen gerçek bir email adresi kullanın.';
    } else {
        // Kayıt işlemine devam et...
    }
}

JavaScript ile Form Doğrulama

Kullanıcı formu göndermeden önce tarayıcı tarafında kontrol yaparak gereksiz sunucu yükünü azaltabilirsiniz:

document.getElementById('kayitForm').addEventListener('submit', async (e) => {
    e.preventDefault();
    const email = document.getElementById('email').value;

    const sonuc = await fetch(
        `https://api.teknikzeka.net/tempmail/api/?action=check&email=${encodeURIComponent(email)}`,
        { headers: { 'X-API-Key': 'API_KEYINIZ' } }
    ).then(r => r.json());

    if (sonuc.success && sonuc.data.blocked) {
        alert('Geçici email adresleri kabul edilmez!');
        return;
    }

    e.target.submit(); // Email temizse formu gönder
});

Python Flask Middleware

import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

def is_disposable(email):
    try:
        r = requests.get(
            'https://api.teknikzeka.net/tempmail/api/',
            params={'action': 'check', 'email': email},
            headers={'X-API-Key': 'API_KEYINIZ'},
            timeout=5
        )
        data = r.json()
        return data.get('success') and data['data'].get('blocked')
    except:
        return False

@app.route('/register', methods=['POST'])
def register():
    email = request.json.get('email', '')
    if is_disposable(email):
        return jsonify({'error': 'Disposable email kabul edilmez'}), 400
    return jsonify({'message': 'Kayıt başarılı'})

Hata Yönetimi

API, hata durumlarında anlamlı HTTP durum kodları ve detaylı hata mesajları döndürür. Uygulamanızda bu hataları doğru şekilde yakalamanız önemlidir.

Örnek hata yanıtı:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Hourly limit exceeded. 50/50 used.",
    "retry_after": 1842
  }
}

retry_after alanı, tekrar deneme yapabileceğiniz süreyi saniye cinsinden belirtir. Bu değeri kullanarak otomatik yeniden deneme mekanizması kurabilirsiniz.

Webhook Bildirimleri (Pro Plan)

Pro plan kullanıcıları, API limitleri aşıldığında otomatik bildirim almak için webhook yapılandırabilir. Kullanıcı panelindeki Ayarlar sekmesinden webhook URL'nizi tanımlayabilirsiniz.

Limit aşıldığında ShieldMail, belirlediğiniz URL'ye şu formatta bir POST isteği gönderir:

{
  "event": "rate_limit_exceeded",
  "user_id": 42,
  "period": "hourly",
  "limit": 1000,
  "current_usage": 1001,
  "timestamp": "2025-03-02T09:45:00Z"
}

En İyi Uygulamalar ve İpuçları

1. Timeout Ayarı Yapın

API isteklerinizde mutlaka bir timeout değeri belirleyin (önerilen: 5 saniye). Böylece API'de olası bir gecikme durumunda uygulamanız askıda kalmaz ve kullanıcı deneyimi olumsuz etkilenmez.

2. Hata Durumunda Kayıt Engellemeyin

API'ye ulaşılamadığında veya timeout oluştuğunda, kayıt işlemini engellemeyin. API yanıt vermezse kullanıcının kaydını kabul edin ve daha sonra kontrol edin. Böylece API kesintisi kullanıcılarınızı etkilemez.

3. Sonuçları Kendi Tarafınızda Önbelleğe Alın

Aynı domain'i tekrar tekrar sorgulamak yerine, sonuçları kendi veritabanınızda veya Redis/Memcached gibi bir cache katmanında saklayın. Bu hem API limitinizi korur hem de yanıt süresini düşürür.

4. Toplu Kontrolü Tercih Edin

Birden fazla email kontrol edecekseniz, her biri için ayrı istek yerine bulk_check endpoint'ini kullanın. Tek istekte birden fazla email kontrolü yaparak hem hız kazanırsınız hem de API çağrı sayınızı azaltırsınız.

5. Hem Sunucu Hem İstemci Tarafında Kontrol Edin

JavaScript ile istemci tarafında anlık geri bildirim verin, ancak son kararı sunucu tarafında PHP/Python/Node.js ile verin. İstemci tarafı kontroller kolayca atlatılabilir.

API Dokümantasyonu ve Destek

Daha fazla bilgi, 14 farklı programlama dilinde kod örnekleri ve detaylı teknik dokümantasyon için:

• API Dokümantasyonu: https://api.teknikzeka.net/tempmail/docs.php
• Kullanıcı Paneli: https://api.teknikzeka.net/tempmail/user/
• Ücretsiz Kayıt: https://api.teknikzeka.net/tempmail/user/?page=register

Ücretsiz plan ile hemen başlayabilir, projeniz büyüdükçe ihtiyacınıza uygun plana geçebilirsiniz. ShieldMail API, web uygulamalarınızı sahte kayıtlardan korumanın en pratik ve güvenilir yollarından biridir.