Source: https://once-email.com/pt/blog/temporary-email-api-testing-guide Testes e engenharia · 7 de ago. de 2026Atualizado 20 de ago. de 2026 # Como usar uma API de e-mail temporário sem criar testes instáveis Projete testes com caixas isoladas, consultas limitadas, tempo máximo, correlação segura e limpeza determinística. [Equipe de engenharia do Once Email, Once Email author Equipe de engenharia do Once Email]() Revisado por Revisão editorial do Once Email O que este guia ajuda você a fazer A equipe obtém um padrão de consulta com orçamento, correlação sem segredos e limites de quota adaptável à própria API. Guia do artigo Por que vale a pena ler este artigo **Análise original** Modelamos o e-mail como sistema assíncrono e separamos criação, espera, seleção, validação e limpeza para eliminar dependências compartilhadas. **Contexto de tendências** Suites CI paralelas e provedores com filas variáveis fazem esperas fixas e caixas reutilizadas falharem de forma intermitente. **Valor prático** A equipe obtém um padrão de consulta com orçamento, correlação sem segredos e limites de quota adaptável à própria API. E-mail não é uma chamada síncrona. O sistema em teste pode enfileirar uma tarefa, o provedor pode atrasar a entrega e filtros podem mudar a ordem. Um teste estável precisa modelar essas etapas em vez de usar ` sleep ` fixo. ## [Uma caixa por caso]() Crie uma caixa isolada para cada execução ou cenário. Não compartilhe endereço entre jobs paralelos. Registre o identificador da caixa apenas no contexto temporário do teste e nunca publique chave de API ou token em logs. Use dados sintéticos e um identificador de correlação não secreto no evento. A caixa não deve receber dados reais de cliente, senha ou documento. ## [Consulta com orçamento]() Depois de disparar a ação, consulte a lista com intervalo crescente e limite total. Por exemplo, espere poucos segundos entre as primeiras tentativas e aumente gradualmente, respeitando o limite de requisições. Encerre com erro claro quando o orçamento acabar. Não faça loop infinito e não crie outra caixa a cada consulta. Criação e troca consomem a quota própria; mensagens recebidas seguem contrato separado. Os valores devem vir da configuração e resposta da API, não de números espalhados no teste. ## [Selecione a mensagem correta]() Correlacione por destinatário, tipo de evento, identificador seguro e horário posterior à solicitação. Assunto sozinho é insuficiente. Se houver duplicata, registre o comportamento esperado e não aceite arbitrariamente a primeira. Valide texto, HTML, idioma, links e expiração sem imprimir segredos. O código de uso único pode ser comparado em memória e redigido imediatamente. ## [Erros e idempotência]() Teste respostas 400, 401, 403, 404 e 429 conforme o contrato. Uma repetição depois de timeout não deve criar caixas indefinidamente. Use chave idempotente quando a API oferecer essa capacidade e trate limites como resultado esperado, não falha de infraestrutura. A documentação pública deve indicar autenticação, quota e retenção antes da abertura comercial. Não construa dependência de um endpoint descrito como candidato até existir versão estável. ## [Limpeza determinística]() Coloque a exclusão da caixa em ` finally `, inclusive quando a asserção falhar. Defina timeout para a própria limpeza e registre somente o resultado. Artefatos de CI devem expirar e não conter corpo da mensagem. A [checklist de testes de e-mail]() cobre apresentação e acessibilidade; este padrão cobre orquestração. Juntos, eles tornam a falha localizável sem esconder a natureza assíncrona do transporte. ## [Métricas úteis]() Meça tempo entre solicitação e primeira observação, número de consultas e taxa de timeout por ambiente. Não publique endereços ou conteúdo. Tendências agregadas ajudam a ajustar orçamento sem transformar uma execução lenta em espera permanente. ## [Contrato de configuração]() Mantenha quota mensal, limite por minuto, duração e máximo de consultas em configuração versionada. O teste pode receber valores diferentes por ambiente, mas deve registrar qual contrato aplicou. Não use “ilimitado” para criações quando existe uma franquia; diferencie explicitamente operações de caixa de mensagens recebidas. Essa separação evita cobrança inesperada e asserções incompatíveis com produção. ## [Diagnostique a etapa, não apenas “o e-mail não chegou”]() Antes de ativar o teste no CI, registre somente etapa, duração limitada, status HTTP, ID de solicitação quando existir, quantidade de candidatos e um ID de execução sem segredo. Não registre endereço, código, link, assunto, corpo, anexo, chave de API nem consulta completa. Classifique antes de repetir: gatilho recusado pertence ao aplicativo; entrega pendente significa que nenhum candidato chegou até o prazo; em ` 429 ` ou ` 503 `, respeite ` Retry-After ` sem ampliar o orçamento; vários candidatos indicam correlação ambígua; destino controlado incorreto é falha de asserção; e falha de limpeza deve ser separada do resultado principal. Confirme também que o provedor documenta API, autenticação, exclusão, expiração e limites. A Once Email ainda não oferece API pública de produção; estes exemplos são padrões independentes de fornecedor, não endpoints disponíveis da Once Email. ## [Use um SDK sem esconder o desenho do teste]() O Once Email oferece candidatos SDK testados para TypeScript, Python, Java, Go, .NET, PHP e Ruby. Comece na [página de SDK]() , escolha a linguagem já usada pelo serviço de teste e revise o diretório de código; não adicione outro runtime apenas para consultar uma caixa. Os candidatos vêm de uma GitHub Release imutável, não de um registro. Compare o arquivo com ` SHA256SUMS `, leia o README incluído e fixe a versão. Comandos npm, PyPI, Maven Central, NuGet, Packagist ou RubyGems não aparecem antes de essas publicações existirem. O SDK reduz serialização HTTP, mas não decide prazo, correspondência ou limpeza. Use uma caixa, um proprietário de polling e um prazo por teste autorizado; respeite ` Retry-After ` no ` 429 `, diferencie ` 503 ` de caixa vazia, rejeite resultados ambíguos e exclua no ` finally `. Confira também o [contrato da API somente de recebimento]() . ## Guias relacionados Checklist de testes de e-mail para desenvolvedores: da solicitação à expiração Um plano reproduzível para verificar geração, entrega, conteúdo, links, anexos, acessibilidade e limpeza sem usar dados reais. [Checklist de testes de e-mail para desenvolvedores: da solicitação à expiração]() Como guardar evidências de testes de e-mail sem expor segredos O que manter, o que ocultar e como demonstrar um resultado sem arquivar códigos, links de acesso ou mensagens completas. [Como guardar evidências de testes de e-mail sem expor segredos]() Postfix vs Dovecot: funções diferentes em um servidor de recebimento Entenda onde Postfix, Dovecot, LMTP, fila e IMAP atuam e use evidências para localizar uma falha de entrega. [Postfix vs Dovecot: funções diferentes em um servidor de recebimento]() [Códigos de verificação por e-mail: como copiar, conferir e usar com segurança Um processo para lidar com códigos de uso único sem compartilhá-los, confundir mensagens antigas nem deixar segredos no portapapéis.]() [O e-mail de verificação não chegou? Diagnóstico seguro passo a passo Uma ordem de verificação para localizar uma mensagem atrasada sem pedir códigos repetidamente nem expor informações sensíveis.]()