API de Verificação de Email: Guia de Integração

Autenticação por Chave de API

O método de autenticação mais comum usa chaves de API passadas em cabeçalhos de requisição ou como parâmetros de consulta. As chaves de API fornecem integração simples enquanto permitem rastreamento de uso e limitação de taxa.

Autenticação Baseada em Cabeçalho

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' })
});

O cabeçalho Authorization com um token Bearer é a abordagem recomendada. Ele mantém as credenciais fora das URLs, prevenindo registro acidental em logs de acesso do servidor.

Autenticação por Parâmetro de Consulta

Algumas APIs aceitam chaves como parâmetros de consulta para integração mais simples em certos contextos:

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

Embora conveniente, a autenticação por parâmetro de consulta expõe credenciais em logs e histórico do navegador. Use autenticação baseada em cabeçalho quando possível.

Práticas Recomendadas para Chaves de API

Variáveis de Ambiente Nunca codifique chaves de API no código fonte. Armazene-as em variáveis de ambiente:

const apiKey = process.env.BV_API_KEY;

Rotação de Chaves Rotacione chaves de API periodicamente e imediatamente se houver suspeita de comprometimento. A maioria dos serviços permite múltiplas chaves ativas para possibilitar rotação sem interrupção.

Chaves Separadas por Ambiente Use chaves de API diferentes para desenvolvimento, staging e produção. Isso impede que o tráfego de teste afete as cotas de produção e simplifica a depuração.

Restringir Permissões de Chaves Se a API suportar permissões com escopo, limite cada chave apenas às operações necessárias. Uma chave usada apenas para verificação de email único não precisa de permissões de processamento em lote.

Endpoints Principais da API

APIs de verificação de email normalmente fornecem endpoints para diferentes casos de uso. Entender o propósito de cada endpoint ajuda a escolher a abordagem certa para sua integração.

Verificação de Email Único

O endpoint fundamental verifica um endereço de email por requisição:

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

Estrutura de Resposta

{
  "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
}

Campos-Chave da Resposta

Verificação de Email em Lote

Para verificar listas grandes, endpoints de lote aceitam múltiplos emails:

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

Endpoints de lote processam emails em paralelo, retornando resultados mais rápido do que requisições sequenciais de email único. A maioria dos serviços limita tamanhos de lote (tipicamente 100-1000 emails por requisição) e pode processar lotes muito grandes de forma assíncrona.

Upload de Arquivo em Massa

Para listas muito grandes para endpoints de lote, APIs de upload de arquivo lidam com milhões de registros:

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();

Endpoints de upload de arquivo retornam um ID de job para rastreamento de progresso. Os resultados são recuperados quando o processamento é concluído:

// Verificar status do job
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();

// Baixar resultados quando concluído
if (status === 'completed') {
  const resultsResponse = await fetch(
    `https://api.billionverify.com/v1/bulk/download/${job_id}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
}

Notificações por Webhook

Para processamento assíncrono, configure webhooks para receber notificações quando a verificação for concluída:

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

Webhooks eliminam polling, melhorando a eficiência para operações em massa.

Estratégias de Tratamento de Erros

Tratamento robusto de erros garante que sua integração lide graciosamente com falhas sem interromper a experiência do usuário.

Códigos de Status HTTP

APIs de verificação de email usam códigos de status HTTP padrão:

Implementando Lógica de Retry

Problemas de rede e erros transitórios requerem mecanismos de retry:

async function verifyEmailWithRetry(email, maxRetries = 3) {
  const delays = [1000, 2000, 4000]; // Exponential backoff

  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) {
        // Rate limited - wait and retry
        const retryAfter = response.headers.get('Retry-After') || delays[attempt];
        await sleep(parseInt(retryAfter) * 1000);
        continue;
      }

      if (response.status >= 500) {
        // Server error - retry with backoff
        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));
}

Tratando Resultados de Validação

Nem toda verificação retorna uma resposta definitiva. Trate resultados incertos apropriadamente:

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) {
    // Can't definitively verify - consider accepting with monitoring
    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' };
}

Limitação de Taxa e Otimização

APIs de verificação de email implementam limites de taxa para garantir uso justo e estabilidade do sistema. Integração eficaz respeita esses limites enquanto maximiza o throughput.

Entendendo Limites de Taxa

Limites de taxa normalmente se aplicam em múltiplos níveis:

• Requisições por segundo: Máximo de chamadas de API por segundo
• Requisições por minuto/hora: Limites de taxa sustentada
• Cotas diárias/mensais: Permissão total de verificação
• Conexões simultâneas: Limites de requisições simultâneas

Verifique os cabeçalhos de resposta para informações de limite de taxa:

const response = await fetch('https://api.billionverify.com/v1/verify', {
  // ... request options
});

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}`);

Implementando Limitação de Taxa

Gerencie proativamente as taxas de requisição para evitar atingir limites:

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();
  }
}

// Usage
const limiter = new RateLimiter(10); // 10 requests per second

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

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

  return results;
}

Otimização de Processamento em Lote

Maximize a eficiência ao verificar múltiplos emails:

Use Endpoints de Lote Requisições únicas para cada email desperdiçam round-trips de rede. Endpoints de lote verificam múltiplos emails por requisição:

// Inefficient: 100 separate requests
for (const email of emails) {
  await verifyEmail(email);
}

// Efficient: 1 batch request
const results = await verifyEmailBatch(emails);

Divida Listas Grandes Divida listas muito grandes em tamanhos de lote ideais:

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 emails per batch
  const results = [];

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

  return results;
}

Processamento Paralelo com Limites Processe múltiplos lotes simultaneamente respeitando limites de taxa:

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;
}

Estratégias de Cache

Fazer cache dos resultados de verificação reduz custos de API e melhora tempos de resposta para emails repetidos.

Quando Fazer Cache

Faça cache dos resultados de verificação quando:

• O mesmo email pode ser verificado múltiplas vezes
• Verificação em tempo real não é crítica
• Otimização de custos é importante

Não faça cache quando:

• Atualidade é crítica (ex.: transações de alto valor)
• Emails mudam de status frequentemente no seu caso de uso
• Custos de armazenamento excedem custos de API

Implementação de Cache

class VerificationCache {
  constructor(ttlMs = 24 * 60 * 60 * 1000) { // 24 hour default 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
    });
  }
}

// Usage
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 };
}

Considerações sobre TTL de Cache

Diferentes tipos de resultado garantem diferentes durações de cache:

Práticas Recomendadas de Segurança

Integrar APIs externas introduz considerações de segurança além da autenticação.

Validação de Entrada

Valide emails antes de enviar para a 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);
}

Registro Seguro

Nunca registre chaves de API completas ou dados sensíveis:

function logApiRequest(email, response) {
  // Don't log: API keys, full email addresses in production
  console.log({
    email_domain: email.split('@')[1],
    status: response.status,
    is_valid: response.is_valid,
    timestamp: new Date().toISOString()
  });
}

Apenas HTTPS

Sempre use HTTPS para comunicações de API. Verifique certificados SSL em produção:

// Node.js - don't disable certificate verification in production
const https = require('https');

const agent = new https.Agent({
  rejectUnauthorized: true // Default, but explicit
});

Integrando com Frameworks Populares

Middleware Express.js

Crie middleware reutilizável para verificação de 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 - don't block registration on API errors
    req.emailVerification = { verified: false, error: error.message };
    next();
  }
};

// Usage
app.post('/register', emailVerificationMiddleware, (req, res) => {
  // req.emailVerification contains verification results
});

Hook React

Crie um hook customizado para verificação de email no 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 };
}

Monitoramento e Análises

Rastreie uso de API e resultados de verificação para otimizar sua integração.

Métricas-Chave para Monitorar

• Tempo de resposta da API: Rastreie tendências de latência
• Taxas de erro: Monitore falhas por tipo
• Taxa de acerto de cache: Meça eficácia do cache
• Distribuição de verificação: Rastreie percentuais válido/inválido/arriscado
• Custo por verificação: Calcule custos reais

Registro para Análises

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 // registration, import, etc.
  };

  // Send to your analytics system
  analytics.track('email_verification', logEntry);
}

Integração com a API BillionVerify

BillionVerify fornece uma API de verificação de email abrangente projetada para desenvolvedores. A API combina múltiplas técnicas de verificação em uma única chamada, entregando resultados rápidos e precisos com insights detalhados.

Início Rápido

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();
}

Recursos

• Verificação em tempo real: Tempos de resposta subsegundo para verificação de email único
• Processamento em lote: Verifique até 1000 emails por requisição
• Upload de arquivo em massa: Processe milhões de registros com processamento assíncrono de job
• Verificações abrangentes: Sintaxe, domínio, MX, SMTP, descartável, detecção catch-all
• Pontuação de risco: Avaliação de risco nuançada além de válido/inválido binário
• Sugestões de erros de digitação: Detecte e sugira correções para erros de digitação comuns
• Suporte a webhook: Receba notificações para conclusão de job em massa

A documentação da API fornece informações detalhadas sobre todos os endpoints, formatos de resposta e exemplos de integração em múltiplas linguagens de programação.

Conclusão

Integrar uma API de verificação de email transforma como sua aplicação lida com qualidade de dados de email. Desde validação em tempo real durante o registro até processamento em lote de listas existentes, as APIs fornecem a infraestrutura para verificação abrangente de email sem a complexidade de construir e manter sistemas de verificação.

Principais conclusões para integração bem-sucedida:

1. Escolha o endpoint certo para seu caso de uso: verificação única para tempo real, lote para listas médias, upload em massa para grandes conjuntos de dados
2. Implemente tratamento robusto de erros com lógica de retry e degradação graciosa
3. Respeite limites de taxa através de throttling do lado do cliente e batching eficiente
4. Faça cache estrategicamente para reduzir custos e melhorar desempenho
5. Monitore e analise resultados de verificação de email para melhorar continuamente a qualidade dos dados

Seja você construindo uma nova aplicação ou melhorando um sistema existente, APIs de verificação de email como BillionVerify fornecem as ferramentas necessárias para garantir que cada endereço de email no seu banco de dados seja válido, entregável e seguro para usar.

Comece sua integração hoje e experimente a diferença que a verificação profissional de email faz para a qualidade de dados e entregabilidade de email da sua aplicação.