Geliştiriciler İçin E-posta Doğrulama API'si: OTP Gönder

E-posta Doğrulama API'si Tam Olarak Ne Yapar?

E-posta doğrulama API'si, kullanıcı kaydının sıkıcı ama kritik kısmını üstlenir: bir kişinin, kayıt formuna yazdığı gelen kutusunu gerçekten kontrol ettiğini doğrulamak. Kendi SMTP altyapınızı kurmak, geri dönen e-postaları yönetmek ve tek kullanımlık şifre mantığını sıfırdan yazmak yerine bir REST uç noktasını çağırırsınız. API kodu gönderir, durumunu saklar ve kullanıcının girdiği kodun doğru olup olmadığını söyler.

Burada birbiriyle ilişkili iki iş var ve bunları en baştan ayırmak faydalı olur:

• Teslim edilebilirlik doğrulaması, herhangi bir şey göndermeden önce adresin gerçek olduğunu ve posta alabileceğini onaylar.
• OTP doğrulaması, o adrese tek kullanımlık bir kod gönderir ve kullanıcının girdisini kontrol eder.

Çoğu ekibin ikisine de ihtiyacı var. Kayıt sırasında yazım hatalarını ve tek kullanımlık adresleri reddetmek, ardından bir kodla sahipliği kanıtlamak istersiniz. Bu rehber, ikisinin nasıl birbirine oturduğuna değinirken asıl olarak OTP akışına odaklanıyor.

Neden Kendiniz Yazmak Yerine API Kullanmalısınız?

Tek bir e-posta göndermek kolaydır. Ölçekte güvenilir, doğrulanabilir ve hız sınırlı e-postalar göndermek değildir. Akışı kendiniz kurduğunuzda uzun bir uç durum listesini de devralırsınız.

• Geri dönenler ve engel listeleri. İtibarı zayıf ham bir SMTP kurulumu spam'e düşer. API, gönderen itibarını sizin için soyutlar.
• Durum yönetimi. Her kodu, süresini, deneme sayısını saklamanız ve güvenle bir oturuma bağlamanız gerekir.
• Yeniden deneme ve hız sınırları. Kötüye kullananlar gönderme uç noktanızı zorlar. Birinin bunu kısıtlaması gerekir.
• Yerelleştirme. Birden fazla dilde kodlar ve şablonlar karmaşıklığı hızla artırır.

İyi bir API bu kaygıları iki çağrıya indirger. SMSBulk, SMS doğrulama uç noktalarını yansıtan bir e-posta doğrulama API'si sunar. Aynı hesaptan zaten SMS kodları alıyorsanız zihinsel model tıpatıp aynıdır. Tek cüzdan, tek kimlik doğrulama anahtarı, iki kanal.

İki Uç Noktalı Model

E-posta ile OTP sunan hemen her API iki işleme indirgenir. İsimlendirme değişir ama yapı tutarlıdır.

1. Kod isteme

Hedef e-posta adresini ve isteğe bağlı olarak şablon kimliği veya dil gibi meta verileri gönderirsiniz. API bir kod üretir, e-postayla gönderir ve kendi tarafınızda saklayacağınız bir istek kimliği döndürür.

POST /api/email/otp/send
Content-Type: application/json
Authorization: Bearer API_ANAHTARINIZ

{
  "email": "[email protected]",
  "locale": "tr",
  "ttl": 300
}

Tipik bir yanıt:

{
  "request_id": "otp_9f2a7c",
  "status": "sent",
  "expires_in": 300
}

O request_id değerini kullanıcının oturumuna bağlı olarak saklayın. Ham kodu tutması için istemciye asla güvenmeyin.

2. Kodu doğrulama

Kullanıcı kodu yapıştırdığında, request_id ile birlikte girdisini gönderirsiniz. API karşılaştırır, deneme sayacını azaltır ve bir karar döndürür.

POST /api/email/otp/verify
Content-Type: application/json
Authorization: Bearer API_ANAHTARINIZ

{
  "request_id": "otp_9f2a7c",
  "code": "482915"
}

Yanıt:

{
  "request_id": "otp_9f2a7c",
  "status": "verified"
}

Hata durumunda invalid_code, expired veya too_many_attempts gibi bir durum alırsınız. Kullanıcının yeniden mi denemesi yoksa yeni kod mu istemesi gerektiğini bilmesi için her birini arayüzde farklı ele alın.

Kodda Minimum Bir Entegrasyon

İki çağrıyı birbirine bağlayan kısa bir Node.js örneği. Aynı desen Python, Go veya PHP'de de geçerlidir.

const API = 'https://api.smsbulk.net';
const KEY = process.env.SMSBULK_KEY;

async function kodGonder(email) {
  const res = await fetch(`${API}/api/email/otp/send`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${KEY}`,
    },
    body: JSON.stringify({ email, ttl: 300 }),
  });
  return res.json(); // { request_id, status }
}

async function kodDogrula(requestId, code) {
  const res = await fetch(`${API}/api/email/otp/verify`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${KEY}`,
    },
    body: JSON.stringify({ request_id: requestId, code }),
  });
  return res.json(); // { status }
}

request_id değerini sunucu tarafında, oturuma bağlı tutun. Tarayıcı yalnızca kullanıcının yazdığı altı haneyi gönderir. Tam istek ve yanıt döngüleriyle daha ayrıntılı bir anlatım isterseniz, kodda e-posta OTP kodlarını alma rehberi aynı akışı baştan sona ele alıyor.

Atlamamanız Gereken Güvenlik Uygulamaları

OTP akışları dikkatsiz kurulduğunda sessizce başarısız olur. Çalışan bir demo yine de kolayca aşılabilir. Bu kuralları en baştan yerleştirin.

Süre sonu ve kısa TTL uygulayın

Kodlar saatlerce değil, dakikalarca yaşamalı. Beş dakikalık bir pencere kullanılabilirlik ile kaba kuvvet riskini dengeler. Süresi dolan kod sunucu tarafında ölür, sadece arayüzde gizlenmez.

Kod başına deneme sınırı koyun

Üç ila beş tahmine izin verin, sonra kodu tamamen geçersiz kılın. Bu olmadan altı haneli bir kod otomatik bir betikle saniyeler içinde tahmin edilebilir.

Gönderme uç noktasını hız sınırlayın

Bir kullanıcı dakikada onlarca e-posta tetiklememeli. IP, hesap ve hedef adres bazında kısıtlayın. Bu hem itibarınızı hem de alıcının gelen kutusunu korur.

Ham kodu asla loglamayın

Uygulama loglarındaki kodlar sızmayı bekleyen bir açıktır. request_id ve sonucu loglayın, hiçbir zaman haneleri değil.

Sabit zamanlı karşılaştırma yapın

Zamanlama yan kanallarından kaçınmak için kod kontrolünde sabit zamanlı karşılaştırma kullanın. Çoğu API sağlayıcısı bunu içeride yapar, ama yerel olarak doğrularsanız naif bir dize eşitliği kullanmayın.

E-posta OTP mi SMS OTP mi: Kanal Seçimi

E-posta ve SMS örtüşen sorunları farklı ödünleşimlerle çözer. E-posta daha ucuzdur ve telefon numarası gerektirmez. SMS bir cihaza daha hızlı ulaşır ve tek kullanımlık gelen kutularıyla kötüye kullanılması zordur. Birçok ürün ikisini de sunar ve kullanıcıya seçtirir, ya da kayıt için e-postayı, parola sıfırlama gibi yüksek riskli işlemler için SMS'i kullanır.

İkisini tartıyorsanız, SMS OTP ile e-posta OTP karşılaştırması her biri için gecikme, maliyet ve güvenliği açıklıyor. Çoğu uygulama için pratik yanıt: hesap oluşturmak için e-posta, ek doğrulama için SMS.

SMSBulk her iki kanalı tek bir API ve tek bir cüzdanın arkasında çalıştırdığı için e-posta ile başlayıp ikinci bir sağlayıcı sözleşmesi olmadan sonradan telefon doğrulaması ekleyebilirsiniz. SMS doğrulama servisi aynı kimlik doğrulama şemasını kullanır, dolayısıyla entegrasyon kodunuz neredeyse hiç değişmez.

Göndermeden Önce Teslim Edilebilirliği Ele Almak

Geçersiz veya tek kullanımlık bir adrese OTP göndermek para israfıdır ve gönderen puanınıza zarar verir. OTP'den önceki bir doğrulama adımı bunların çoğunu yakalar.

• Söz dizimi kontrolü. Bozuk adresleri hem istemci hem sunucu tarafında reddedin.
• Alan adı ve MX kontrolü. Alan adının var olduğunu ve posta kabul ettiğini onaylayın.
• Tek kullanımlık tespiti. Bilinen geçici alan adlarını kayıt sırasında işaretleyin.

Bu filtreyi önce çalıştırmak, OTP gönderim oranınızı temiz tutar, geri dönenleri azaltır ve meşru kullanıcılar kodlarını güvenilir şekilde alır. Doğrulama ile OTP'yi bir boru hattı olarak düşünün: doğrula, sonra gönder, sonra sahipliği kanıtla.

Sık Karşılaşılan Hatalar ve Ayıklama

Bir entegrasyon aksadığında sebep genellikle birkaç şeyden biridir.

• Kod hiç gelmiyor. Önce spam yerleşimini kontrol edin, sonra gönderme çağrısının yumuşak bir hata değil sent döndürdüğünü doğrulayın. Genelde suçlu API değil, teslim edilebilirliktir.
• Sürekli invalid_code. Muhtemelen yanlış request_id ile doğruluyorsunuz ya da kullanıcı eski bir oturumda. Eşleşmeyi loglayın.
• Çok erken expired. TTL'niz çok kısa ya da saat kayması karşılaştırmaları etkiliyor. Her şey için sunucu saatini kullanın.
• Hız sınırı reddi. Meşru yeniden denemeler kısıtınıza takılıyor. Kullanıcıların düğmeye spam yapmaması için arayüze görünür bir bekleme sayacı ekleyin.

İyi gözlemlenebilirlik bunları hızlı düzeltmelere çevirir. Her gönderme ve doğrulama çağrısı için request_id, durum ve zaman damgasını loglayın. Geliştirici dokümantasyonu tüm durum kodları ve hata biçimlerini listeler, böylece bunları işleyicinizde eşleştirebilirsiniz.

En İyi Uygulamalar Kontrol Listesi

Yayına almadan önce bu listeyi gözden geçirin.

• Kodlar altı hane veya daha fazla ve sunucu tarafında rastgele üretiliyor.
• TTL kısa ve sadece görsel değil sunucu tarafında uygulanıyor.
• Kod başına deneme sınırlı, sonra kod geçersiz kılınıyor.
• Gönderme ve doğrulama uç noktalarının ikisi de hız sınırlı.
• Ham kod loglarda veya istemci deposunda asla görünmüyor.
• Kullanıcılar süresi dolmuş, yanlış ve hız sınırlı durumlar için farklı mesajlar alıyor.
• Bekleme süreli bir yeniden gönderme seçeneği var.
• Önemli olduğu yerde göndermeden önce teslim edilebilirlik kontrol ediliyor.

Her maddeyi işaretleyin, e-posta OTP akışınız güvenli, hızlı ve kullanımı keyifli olsun.

SMSBulk ile Başlayın

SMSBulk, temiz bir REST API üzerinden e-posta OTP gönderme ve doğrulama sunar; hepsi SMS doğrulama numaraları ve seyahat eSIM'leriyle aynı hesap ve cüzdanla desteklenir. Tutarlı uç noktalar, şeffaf fiyatlandırma ve ihtiyaç duyduğunuzda e-postadan SMS'e büyüyen tek bir entegrasyon elde edersiniz. Bir hesap açın, API anahtarınızı ekleyin ve bu rehberdeki iki çağrılı akışı bir öğleden sonrada kurun. Bugün e-posta doğrulama API'si ile geliştirmeye başlayın ve kullanıcılarınızın güvendiği bir doğrulama deneyimi yayınlayın.