Mart 2, 2026
Okuma süresi: 8 dakika
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, 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:
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.
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.
ShieldMail API, farklı ihtiyaçlara yönelik esnek planlar sunmaktadır:
| Özellik | Free | Basic | Pro |
|---|---|---|---|
| Saatlik Limit | 50 | 200 | 1.000 |
| Günlük Limit | 500 | 2.000 | 10.000 |
| Aylık Limit | 5.000 | 30.000 | 200.000 |
| Domain Sayısı | 1 | 3 | 10 |
| Toplu Kontrol | 5 email | 20 email | 100 email |
| Cache | ✗ | ✓ | ✓ |
| Webhook | ✗ | ✗ | ✓ |
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.
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_HERE2. Query Parametresi:
?key=sm_YOUR_API_KEY_HEREGüvenlik açısından header yöntemi önerilir, çünkü query parametreleri sunucu loglarında görünür kalabilir.
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_HEREBaş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 durumunuzBirden 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
}Mevcut planınızın limitlerini ve ne kadar kullandığınızı görmek için:
GET https://api.teknikzeka.net/tempmail/api/?action=usageBu endpoint; plan bilgilerinizi, limitlerinizi, mevcut kullanımınızı ve kalan hakkınızı detaylı olarak döndürür.
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...
}
}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
});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ı'})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.
| HTTP Kodu | Hata Kodu | Açıklama |
|---|---|---|
| 401 | AUTH_REQUIRED |
API key gönderilmemiş |
| 401 | INVALID_KEY |
Geçersiz API key |
| 403 | NO_DOMAIN_DEFINED |
Panelden domain tanımlanmamış |
| 403 | DOMAIN_NOT_ALLOWED |
İstek yapılan domain yetkilendirilmemiş |
| 429 | RATE_LIMITED |
Kullanım limiti aşıldı |
| 400 | MISSING_PARAM |
Gerekli parametre eksik |
Ö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.
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"
}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.
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.
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.
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.
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.
Daha fazla bilgi, 14 farklı programlama dilinde kod örnekleri ve detaylı teknik dokümantasyon için:
Ü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.