Quando integri un'API di verifica email nella tua applicazione, l'integrazione in sé è di solito semplice: esegui una richiesta POST e ottieni una risposta JSON. Ma cosa succede quando devi verificare 100.000 email? Oppure quando l'API restituisce un errore di limite di frequenza? O quando vuoi una verifica in tempo reale senza bloccare il flusso di registrazione?
Questa guida tratta le tre cose di cui ogni integrazione di verifica email in produzione ha bisogno: limitazione intelligente della frequenza, elaborazione asincrona basata su webhook e gestione robusta degli errori. Include esempi di codice funzionanti in Python, JavaScript e PHP.
Pattern architetturali per le API di verifica email
Pattern 1: verifica sincrona (in tempo reale)
Da usare quando: verifichi una singola email in tempo reale — moduli di registrazione, flussi di checkout, raccolta di lead.
Client → Your Server → Verification API → Response → Your Server → Client
Latenza: 200–800 ms (un round-trip SMTP). Abbastanza veloce per la maggior parte dell'esperienza utente, ma percepibile se chiamato in linea.
Pattern 2: verifica asincrona (batch)
Da usare quando: verifichi elenchi di 1.000+ email — importazioni in blocco, pulizia delle liste, job pianificati.
Client → Your Server → Queue Job → Worker → Verification API → Store Results
↓
Client polls or receives webhook when complete
Pattern 3: verifica basata su webhook
Da usare quando: vuoi una verifica in tempo reale senza tenere aperta la connessione del client.
Client → Your Server → Submit Job (returns job_id)
↓
Your Server → Verification API → POST webhook → Update database
↓
Client polls or receives notification when job completes
Limitazione della frequenza: come verificare milioni di email senza essere bloccati
Comprendere i limiti di frequenza
| Tipo di limite | Esempio | Applicazione |
|---|---|---|
| Richieste al secondo (RPS) | 50 RPS | Token bucket: burst fino al limite, poi attesa |
| Richieste al minuto (RPM) | 500 RPM | Finestra scorrevole |
| Richieste al giorno | 50.000/giorno | Finestra fissa, si azzera a mezzanotte UTC |
| Connessioni simultanee | 10 simultanee | Limite del pool di connessioni |
Strategia 1: Token Bucket Rate Limiter (Python)
import time
import threading
class TokenBucket:
"""Rate limiter che consente picchi fino a `capacity`, si ricarica a `rate` al secondo."""
def __init__(self, rimbalzo: float, capacity: int):
self.rimbalzo = rimbalzo
self.capacity = capacity
self.tokens = capacity
self.last_refill = time.monotonic()
self.lock = threading.Lock()
def acquire(self) -> bool:
with self.lock:
now = time.monotonic()
elapsed = now - self.last_refill
self.tokens = min(self.capacity, self.tokens + elapsed * self.rimbalzo)
self.last_refill = now
if self.tokens >= 1:
self.tokens -= 1
return True
return False
def wait_and_acquire(self) -> None:
while non self.acquire():
time.sleep(0.05)
# Utilizzo: 50 richieste al secondo, burst fino a 100
rate_limiter = TokenBucket(rimbalzo=50, capacity=100)
def verify_email(email: str) -> dict:
rate_limiter.wait_and_acquire()
response = requests.post(
"https://api.email-validator.com/v1/verify",
json={"email": email},
headers={"Authorization": f"Bearer {API_KEY}"}
)
return response.json()
Strategia 2: Coda + Pool di Worker (Elaborazione in Blocco)
from concurrent.futures import ThreadPoolExecutor, as_completed
from queue import Queue
def bulk_verify(email: list[str], max_workers: int = 5, max_rps: int = 50) -> dict:
limiter = TokenBucket(rimbalzo=max_rps, capacity=max_rps * 2)
results = {}
queue = Queue()
for email in email:
queue.put(email)
def worker():
while non queue.vuoto():
try:
email = queue.get_nowait()
except:
interrompi
limiter.wait_and_acquire()
try:
result = verify_email(email)
results[email] = result
except Eccezione as e:
results[email] = {"error": str(e)}
finally:
queue.task_done()
with ThreadPoolExecutor(max_workers=max_workers) as executor:
futures = [executor.submit(worker) for _ in intervallo(max_workers)]
for future in as_completed(futures):
future.result()
return results
Strategia 3: Backoff esponenziale (JavaScript/Node.js)
async function verifyEmailWithRetry(email, maxRetries = 5) {
let tentativo = 0;
while (tentativo < maxRetries) {
const response = await fetch('https://api.email-validator.com/v1/verify', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ email }),
});
if (response.status === 429) {
tentativo++;
const retryAfter = response.headers.get('Retry-After');
const delay = retryAfter
? parseInt(retryAfter) * 1000
: Math.min(1000 * Math.pow(2, tentativo), 60000);
console.warn(`Limite di frequenza superato. Nuovo tentativo tra ${delay}ms (${tentativo}/${maxRetries})`);
await sleep(delay);
continue;
}
if (!response.ok) {
throw new Errore(`Errore API: ${response.status}`);
}
return await response.json();
}
throw new Errore(`Fallito dopo ${maxRetries} tentativi`);
}
function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
Webhook: verifica asincrona senza polling
Implementare un ricevitore di Webhook (PHP)
<?php
// webhook_receiver.php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EMAILVERIFY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, getenv('WEBHOOK_SECRET'));
if (!hash_equals($expected, $signature)) {
http_response_code(401);
die('Firma non valida');
}
$data = json_decode($payload, true);
if (!isset($data['job_id'], $data['status'], $data['results'])) {
http_response_code(400);
die('Payload non valido');
}
$db = new PDO('mysql:host=localhost;dbname=email_verifier', 'user', 'pass');
foreach ($data['results'] as $result) {
$stmt = $db->prepare('
UPDATE email_queue
SET status = :status, result = :result, verified_at = NOW()
WHERE email = :email AND job_id = :job_id
');
$stmt->execute([
'status' => $result['status'],
'result' => json_encode($result),
'email' => $result['email'],
'job_id' => $data['job_id'],
]);
}
http_response_code(200);
echo json_encode(['ricevuto' => true]);
Sicurezza del webhook
| Pratica | Perché |
|---|---|
| Verifica della firma HMAC | Dimostra che la richiesta proviene dall'API |
| Whitelist degli IP | Accetta solo da intervalli IP noti |
| Chiavi di idempotenza | Evita l'elaborazione di webhook duplicati |
| Gestione dei tentativi | I webhook possono arrivare più volte |
| Conferma tempestiva | Rispondi rapidamente con 200, elabora in modo asincrono |
Gestione degli errori
Codici di stato HTTP e la tua risposta
| Stato | Errore | Cosa fare |
|---|---|---|
| 400 | Richiesta non valida | Convalida l'input lato client |
| 401 | Non autorizzato | Controlla la chiave API, non riprovare |
| 402 | Pagamento richiesto | Passa a un piano superiore o attendi il ripristino della quota |
| 429 | Troppe richieste | Backoff esponenziale |
| 422 | Non elaborabile | Risultato valido: email non verificabile, non è un errore |
| 500 | Errore interno del server | Riprova con backoff, monitoraggio con avvisi |
| 503 | Servizio non disponibile | Riprova dopo Retry-After header value |
Gestore robusto degli errori (Python)
import time
import requests
class VerificationAPIError(Eccezione):
pass
def verify_email_safe(email: str, max_retries: int = 3) -> dict:
retryable = {429, 500, 502, 503}
for tentativo in intervallo(1, max_retries + 1):
try:
response = requests.post(
"https://api.email-validator.com/v1/verify",
json={"email": email},
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10
)
if response.status_code == 200:
return response.json()
if response.status_code == 401:
raise VerificationAPIError("Chiave API non valida")
if response.status_code == 402:
raise VerificationAPIError("Quota superata")
if response.status_code == 422:
return response.json() # risultato valido, non un errore
if response.status_code in retryable:
if tentativo == max_retries:
raise VerificationAPIError(f"Non disponibile dopo {max_retries} tentativi")
time.sleep(min(2 ** tentativo, 30))
continue
raise VerificationAPIError(f"Stato imprevisto: {response.status_code}")
except requests.eccezioni.Timeout:
if tentativo == max_retries:
raise VerificationAPIError("Richiesta scaduta ripetutamente")
time.sleep(min(2 ** tentativo, 30))
return None
Checklist per la produzione
□ Frequenza limitazione implementato (token bucket o queue-basato)
□ esponenziale backoff su 429/5xx risposte
□ Webhook firma verifica (HMAC-SHA256)
□ Webhook idempotenza (job_id + event_id deduplicazione)
□ Tutti API chiamate hanno timeout (5–10 secondi massimo)
□ API chiave memorizzati in ambiente variabili solo
□ Errore logging with retry conteggi
□ Monitoraggio/avvisi for prolungato error rimbalzo aumento
□ Degradazione graduale if API è fuori servizio (nonbloccare le registrazioni degli utenti)
Punti chiave
- Sincrono per i moduli di registrazione; asincrono + webhook per le liste in blocco
- Token bucket gestisce i picchi in modo efficiente — implementalo prima che serva
- Backoff esponenziale su 429/5xx — 1s → 2s → 4s → 8s → max 60s
- Verifica le firme dei webhook con HMAC — non fidarti mai delle POST in arrivo
- 422 è un risultato valido— le email non verificabili non sono errori dell'API
- Non bloccare mai le registrazioni degli utenti se l'API non è disponibile — metti in coda e riprova
- Imposta i timeout su ogni chiamata — i timeout TCP predefiniti possono superare i 60 secondi
