API Weryfikacji Email: Przewodnik Integracji

Uwierzytelnianie Oparte na Nagłówkach

const response = await fetch('https://api.billionverify.com/v1/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email: 'user@example.com' })
});

Nagłówek Authorization z tokenem Bearer to zalecane podejście. Utrzymuje dane uwierzytelniające poza URL-ami, zapobiegając przypadkowemu logowaniu w logach dostępu serwera.

Uwierzytelnianie Parametrem Zapytania

Niektóre API akceptują klucze jako parametry zapytania dla prostszej integracji w określonych kontekstach:

GET https://api.billionverify.com/v1/verify?email=user@example.com&api_key=YOUR_API_KEY

Choć wygodne, uwierzytelnianie parametrem zapytania ujawnia dane uwierzytelniające w logach i historii przeglądarki. Gdy to możliwe, używaj uwierzytelniania opartego na nagłówkach.

Najlepsze Praktyki Kluczy API

Zmienne Środowiskowe Nigdy nie umieszczaj kluczy API na stałe w kodzie źródłowym. Przechowuj je w zmiennych środowiskowych:

const apiKey = process.env.BV_API_KEY;

Rotacja Kluczy Okresowo rotuj klucze API i natychmiast po podejrzeniu kompromitacji. Większość usług pozwala na wiele aktywnych kluczy, umożliwiając płynną rotację.

Osobne Klucze dla Każdego Środowiska Używaj różnych kluczy API dla środowisk rozwojowych, staging i produkcyjnych. Zapobiega to wpływowi ruchu testowego na limity produkcyjne i upraszcza debugowanie.

Ograniczanie Uprawnień Kluczy Jeśli API obsługuje ograniczone uprawnienia, ogranicz każdy klucz tylko do potrzebnych operacji. Klucz używany tylko do weryfikacji pojedynczego email nie potrzebuje uprawnień do przetwarzania wsadowego.

Podstawowe Punkty Końcowe API

API weryfikacji email zazwyczaj zapewniają punkty końcowe dla różnych przypadków użycia. Zrozumienie celu każdego punktu końcowego pomaga wybrać właściwe podejście do Twojej integracji.

Weryfikacja Pojedynczego Email

Podstawowy punkt końcowy weryfikuje jeden adres email na żądanie:

POST /v1/verify
{
  "email": "user@example.com"
}

Struktura Odpowiedzi

{
  "email": "user@example.com",
  "is_valid": true,
  "is_deliverable": true,
  "is_disposable": false,
  "is_role_based": false,
  "is_catch_all": false,
  "is_free_provider": true,
  "syntax_valid": true,
  "domain_valid": true,
  "mx_found": true,
  "smtp_check": "passed",
  "risk_score": 15,
  "suggestion": null,
  "verification_time_ms": 1234
}

Kluczowe Pola Odpowiedzi

Wsadowa Weryfikacja Email

Dla weryfikacji dużych list, punkty końcowe wsadowe akceptują wiele adresów email:

POST /v1/verify/batch
{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ]
}

Punkty końcowe wsadowe przetwarzają emaile równolegle, zwracając wyniki szybciej niż sekwencyjne żądania pojedynczych adresów. Większość usług ogranicza rozmiar wsadu (zazwyczaj 100-1000 adresów na żądanie) i może przetwarzać bardzo duże wsady asynchronicznie.

Masowe Przesyłanie Plików

Dla list zbyt dużych dla punktów końcowych wsadowych, API przesyłania plików obsługują miliony rekordów:

const formData = new FormData();
formData.append('file', emailListFile);

const uploadResponse = await fetch('https://api.billionverify.com/v1/bulk/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const { job_id } = await uploadResponse.json();

Punkty końcowe przesyłania plików zwracają identyfikator zadania do śledzenia postępu. Wyniki są pobierane po zakończeniu przetwarzania:

// Sprawdź status zadania
const statusResponse = await fetch(
  `https://api.billionverify.com/v1/bulk/status/${job_id}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

const { status, progress, estimated_completion } = await statusResponse.json();

// Pobierz wyniki po zakończeniu
if (status === 'completed') {
  const resultsResponse = await fetch(
    `https://api.billionverify.com/v1/bulk/download/${job_id}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
}

Powiadomienia Webhook

Dla przetwarzania asynchronicznego skonfiguruj webhooki, aby otrzymywać powiadomienia po zakończeniu weryfikacji:

POST /v1/webhooks
{
  "url": "https://yourapp.com/webhooks/email-verification",
  "events": ["bulk.completed", "bulk.failed"],
  "secret": "your_webhook_secret"
}

Webhooki eliminują odpytywanie, poprawiając wydajność operacji wsadowych.

Strategie Obsługi Błędów

Solidna obsługa błędów zapewnia, że Twoja integracja sprawnie radzi sobie z awariami bez zakłócania doświadczenia użytkownika.

Kody Statusu HTTP

API weryfikacji email używają standardowych kodów statusu HTTP:

Implementacja Logiki Ponawiania

Problemy sieciowe i błędy przejściowe wymagają mechanizmów ponawiania:

async function verifyEmailWithRetry(email, maxRetries = 3) {
  const delays = [1000, 2000, 4000]; // Wykładnicze wycofywanie

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.billionverify.com/v1/verify', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.BV_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ email })
      });

      if (response.status === 429) {
        // Ograniczenie częstotliwości - poczekaj i powtórz
        const retryAfter = response.headers.get('Retry-After') || delays[attempt];
        await sleep(parseInt(retryAfter) * 1000);
        continue;
      }

      if (response.status >= 500) {
        // Błąd serwera - powtórz z wycofywaniem
        await sleep(delays[attempt]);
        continue;
      }

      if (!response.ok) {
        throw new Error(`API error: ${response.status}`);
      }

      return await response.json();

    } catch (error) {
      if (attempt === maxRetries - 1) {
        throw error;
      }
      await sleep(delays[attempt]);
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Obsługa Wyników Walidacji

Nie każda weryfikacja zwraca definitywną odpowiedź. Odpowiednio obsługuj niepewne wyniki:

function handleVerificationResult(result) {
  if (result.is_valid && result.is_deliverable) {
    return { status: 'valid', action: 'accept' };
  }

  if (!result.syntax_valid || !result.domain_valid) {
    return { status: 'invalid', action: 'reject' };
  }

  if (result.is_disposable) {
    return { status: 'risky', action: 'reject_or_warn' };
  }

  if (result.is_catch_all) {
    // Nie można definitywnie zweryfikować - rozważ akceptację z monitorowaniem
    return { status: 'uncertain', action: 'accept_with_caution' };
  }

  if (result.risk_score > 70) {
    return { status: 'high_risk', action: 'manual_review' };
  }

  return { status: 'unknown', action: 'accept_with_monitoring' };
}

Ograniczanie Częstotliwości i Optymalizacja

API weryfikacji email implementują ograniczenia częstotliwości, aby zapewnić sprawiedliwe użycie i stabilność systemu. Skuteczna integracja respektuje te limity, jednocześnie maksymalizując przepustowość.

Zrozumienie Limitów Częstotliwości

Limity częstotliwości zazwyczaj stosują się na wielu poziomach:

• Żądania na sekundę: Maksymalna liczba wywołań API na sekundę
• Żądania na minutę/godzinę: Limity trwałej częstotliwości
• Limity dzienne/miesięczne: Całkowity przydział weryfikacji
• Równoczesne połączenia: Limity jednoczesnych żądań

Sprawdź nagłówki odpowiedzi dla informacji o limitach częstotliwości:

const response = await fetch('https://api.billionverify.com/v1/verify', {
  // ... opcje żądania
});

const rateLimit = response.headers.get('X-RateLimit-Limit');
const remaining = response.headers.get('X-RateLimit-Remaining');
const resetTime = response.headers.get('X-RateLimit-Reset');

console.log(`Rate limit: ${remaining}/${rateLimit}, resets at ${resetTime}`);

Implementacja Ograniczania Częstotliwości

Proaktywnie zarządzaj częstotliwością żądań, aby uniknąć osiągnięcia limitów:

class RateLimiter {
  constructor(requestsPerSecond) {
    this.interval = 1000 / requestsPerSecond;
    this.lastRequest = 0;
  }

  async waitForSlot() {
    const now = Date.now();
    const timeSinceLastRequest = now - this.lastRequest;

    if (timeSinceLastRequest < this.interval) {
      await sleep(this.interval - timeSinceLastRequest);
    }

    this.lastRequest = Date.now();
  }
}

// Użycie
const limiter = new RateLimiter(10); // 10 żądań na sekundę

async function verifyEmailsWithRateLimit(emails) {
  const results = [];

  for (const email of emails) {
    await limiter.waitForSlot();
    const result = await verifyEmail(email);
    results.push(result);
  }

  return results;
}

Optymalizacja Przetwarzania Wsadowego

Maksymalizuj wydajność podczas weryfikacji wielu adresów email:

Używaj Punktów Końcowych Wsadowych Pojedyncze żądania dla każdego adresu marnują podróże sieciowe w obie strony. Punkty końcowe wsadowe weryfikują wiele adresów na żądanie:

// Nieefektywne: 100 osobnych żądań
for (const email of emails) {
  await verifyEmail(email);
}

// Efektywne: 1 żądanie wsadowe
const results = await verifyEmailBatch(emails);

Dziel Duże Listy Podziel bardzo duże listy na optymalne rozmiary wsadów:

function chunkArray(array, chunkSize) {
  const chunks = [];
  for (let i = 0; i < array.length; i += chunkSize) {
    chunks.push(array.slice(i, i + chunkSize));
  }
  return chunks;
}

async function verifyLargeList(emails) {
  const chunks = chunkArray(emails, 100); // 100 adresów na wsad
  const results = [];

  for (const chunk of chunks) {
    const batchResults = await verifyEmailBatch(chunk);
    results.push(...batchResults);
  }

  return results;
}

Przetwarzanie Równoległe z Limitami Przetwarzaj wiele wsadów jednocześnie, szanując limity częstotliwości:

async function verifyWithConcurrency(emails, concurrency = 5) {
  const chunks = chunkArray(emails, 100);
  const results = [];

  for (let i = 0; i < chunks.length; i += concurrency) {
    const batch = chunks.slice(i, i + concurrency);
    const batchResults = await Promise.all(
      batch.map(chunk => verifyEmailBatch(chunk))
    );
    results.push(...batchResults.flat());
  }

  return results;
}

Strategie Cachowania

Cachowanie wyników weryfikacji redukuje koszty API i poprawia czasy odpowiedzi dla powtarzających się adresów email.

Kiedy Cachować

Cachuj wyniki weryfikacji, gdy:

• Ten sam email może być weryfikowany wiele razy
• Weryfikacja w czasie rzeczywistym nie jest krytyczna
• Optymalizacja kosztów jest ważna

Nie cachuj, gdy:

• Świeżość jest krytyczna (np. transakcje o wysokiej wartości)
• Adresy email często zmieniają status w Twoim przypadku użycia
• Koszty przechowywania przekraczają koszty API

Implementacja Cache

class VerificationCache {
  constructor(ttlMs = 24 * 60 * 60 * 1000) { // domyślnie 24 godziny TTL
    this.cache = new Map();
    this.ttl = ttlMs;
  }

  get(email) {
    const entry = this.cache.get(email.toLowerCase());

    if (!entry) return null;

    if (Date.now() > entry.expiry) {
      this.cache.delete(email.toLowerCase());
      return null;
    }

    return entry.result;
  }

  set(email, result) {
    this.cache.set(email.toLowerCase(), {
      result,
      expiry: Date.now() + this.ttl
    });
  }
}

// Użycie
const cache = new VerificationCache();

async function verifyEmailCached(email) {
  const cached = cache.get(email);
  if (cached) {
    return { ...cached, fromCache: true };
  }

  const result = await verifyEmail(email);
  cache.set(email, result);

  return { ...result, fromCache: false };
}

Rozważania Dotyczące TTL Cache

Różne typy wyników wymagają różnych czasów trwania cache:

Najlepsze Praktyki Bezpieczeństwa

Integracja zewnętrznych API wprowadza zagadnienia bezpieczeństwa wykraczające poza uwierzytelnianie.

Walidacja Wejścia

Waliduj adresy email przed wysłaniem do API:

function isValidEmailFormat(email) {
  if (typeof email !== 'string') return false;
  if (email.length > 254) return false;

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

async function verifyEmailSafely(email) {
  if (!isValidEmailFormat(email)) {
    return { is_valid: false, reason: 'Invalid format' };
  }

  return await verifyEmail(email);
}

Bezpieczne Logowanie

Nigdy nie loguj pełnych kluczy API ani wrażliwych danych:

function logApiRequest(email, response) {
  // Nie loguj: kluczy API, pełnych adresów email w produkcji
  console.log({
    email_domain: email.split('@')[1],
    status: response.status,
    is_valid: response.is_valid,
    timestamp: new Date().toISOString()
  });
}

Tylko HTTPS

Zawsze używaj HTTPS do komunikacji z API. Weryfikuj certyfikaty SSL w produkcji:

// Node.js - nie wyłączaj weryfikacji certyfikatu w produkcji
const https = require('https');

const agent = new https.Agent({
  rejectUnauthorized: true // Domyślnie, ale jawnie
});

Integracja z Popularnymi Frameworkami

Middleware Express.js

Utwórz wielokrotnego użytku middleware do weryfikacji email:

const emailVerificationMiddleware = async (req, res, next) => {
  const { email } = req.body;

  if (!email) {
    return next();
  }

  try {
    const result = await verifyEmail(email);
    req.emailVerification = result;

    if (!result.is_valid) {
      return res.status(400).json({
        error: 'Invalid email address',
        details: result
      });
    }

    next();
  } catch (error) {
    // Fail open - nie blokuj rejestracji w przypadku błędów API
    req.emailVerification = { verified: false, error: error.message };
    next();
  }
};

// Użycie
app.post('/register', emailVerificationMiddleware, (req, res) => {
  // req.emailVerification zawiera wyniki weryfikacji
});

Hook React

Utwórz niestandardowy hook do weryfikacji email w frontend:

import { useState, useCallback } from 'react';
import debounce from 'lodash/debounce';

function useEmailVerification() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const verify = useCallback(
    debounce(async (email) => {
      if (!email || !email.includes('@')) {
        setResult(null);
        return;
      }

      setLoading(true);
      setError(null);

      try {
        const response = await fetch('/api/verify-email', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ email })
        });

        const data = await response.json();
        setResult(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }, 500),
    []
  );

  return { verify, result, loading, error };
}

Monitorowanie i Analityka

Śledź użycie API i wyniki weryfikacji, aby zoptymalizować swoją integrację.

Kluczowe Metryki do Monitorowania

• Czas odpowiedzi API: Śledź trendy opóźnień
• Wskaźniki błędów: Monitoruj awarie według typu
• Współczynnik trafień cache: Mierz skuteczność cachowania
• Rozkład weryfikacji: Śledź procenty prawidłowych/nieprawidłowych/ryzykownych
• Koszt na weryfikację: Oblicz rzeczywiste koszty

Logowanie dla Analityki

function logVerification(email, result, metadata) {
  const logEntry = {
    timestamp: new Date().toISOString(),
    email_domain: email.split('@')[1],
    is_valid: result.is_valid,
    is_deliverable: result.is_deliverable,
    is_disposable: result.is_disposable,
    risk_score: result.risk_score,
    response_time_ms: metadata.responseTime,
    from_cache: metadata.fromCache,
    source: metadata.source // rejestracja, import, itp.
  };

  // Wyślij do swojego systemu analityki
  analytics.track('email_verification', logEntry);
}

Integracja API BillionVerify

BillionVerify dostarcza kompleksowe API weryfikacji email zaprojektowane dla programistów. API łączy wiele technik weryfikacji w jednym wywołaniu, dostarczając szybkie, dokładne wyniki ze szczegółowymi informacjami.

Szybki Start

async function verifyWithBillionVerify(email) {
  const response = await fetch('https://api.billionverify.com/v1/verify', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BV_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email })
  });

  return await response.json();
}

Funkcje

• Weryfikacja w czasie rzeczywistym: Czasy odpowiedzi poniżej sekundy dla weryfikacji pojedynczego adresu
• Przetwarzanie wsadowe: Weryfikuj do 1000 adresów na żądanie
• Masowe przesyłanie plików: Przetwarzaj miliony rekordów z asynchronicznym przetwarzaniem zadań
• Kompleksowe sprawdzenia: Składnia, domena, MX, SMTP, wykrywanie tymczasowych, wykrywanie catch-all
• Ocena ryzyka: Niuansowana ocena ryzyka wykraczająca poza binarny prawidłowy/nieprawidłowy
• Sugestie literówek: Wykrywaj i sugeruj korekty dla powszechnych literówek
• Wsparcie webhook: Otrzymuj powiadomienia o zakończeniu zadań wsadowych

Dokumentacja API dostarcza szczegółowych informacji o wszystkich punktach końcowych, formatach odpowiedzi i przykładach integracji w wielu językach programowania.

Poznaj również najlepsze praktyki weryfikacji email i dowiedz się, jak profesjonalna walidacja wpływa na dostarczalność w naszym przewodniku optymalizacji dostarczalności e-maili.

Podsumowanie

Integracja API weryfikacji email transformuje sposób, w jaki Twoja aplikacja obsługuje jakość danych email. Od walidacji w czasie rzeczywistym podczas rejestracji po wsadowe przetwarzanie istniejących list, API zapewniają infrastrukturę do kompleksowej weryfikacji email bez złożoności budowania i utrzymywania systemów weryfikacji.

Kluczowe wnioski dla udanej integracji:

1. Wybierz odpowiedni punkt końcowy dla swojego przypadku użycia: pojedyncza weryfikacja dla czasu rzeczywistego, wsad dla średnich list, masowe przesyłanie dla dużych zestawów danych
2. Implementuj solidną obsługę błędów z logiką ponawiania i graceful degradation
3. Szanuj limity częstotliwości poprzez ograniczanie po stronie klienta i efektywne wsadowanie
4. Cachuj strategicznie, aby zmniejszyć koszty i poprawić wydajność
5. Monitoruj i analizuj wyniki weryfikacji, aby stale poprawiać jakość danych

Czy budujesz nową aplikację, czy ulepszasz istniejący system, API weryfikacji email, takie jak BillionVerify, dostarczają narzędzi potrzebnych do zapewnienia, że każdy adres email w Twojej bazie danych jest prawidłowy, dostarczalny i bezpieczny w użyciu.

Rozpocznij swoją integrację już dziś i doświadcz różnicy, jaką profesjonalna weryfikacja email robi dla jakości danych i dostarczalności email Twojej aplikacji.