Tutoriais · 2026
2026: como integrar a API Mailgun Inbox Placement Test ao CI?
Este guia ajuda você a conectar o teste Inbox Placement ao envio de e-mails do seu próprio produto no CI. Veja como configurar a chave, tratar retentativas e separar o relatório de sementes da validação real do fluxo de e-mail.
2026: como integrar a API Mailgun Inbox Placement Test ao CI?Este guia ajuda você a conectar o teste Inbox Placement ao envio de e-mails do seu próprio produto no CI. Veja como configurar a chave, tratar retentativas e separar o relatório de sementes da validação real do fluxo de e-mail.
Neste artigo
O job do CI envia o e-mail, mas você não sabe se o relatório de posicionamento foi criado ou se a mensagem chegou a uma caixa de entrada real.
Se a conta já tiver o Inbox Placement habilitado, associe o envio normal do Mailgun Send API ao teste com o:inbox-placement-test-key; reutilize a mesma chave nas retentativas da mesma execução lógica. O relatório da Inbox Placement Seed List mostra o resultado das caixas-semente, mas não comprova que o e-mail do seu produto, o link de verificação ou o fluxo de cadastro funcionaram para um destinatário real.
Este guia é para você que mantém o CI e precisa testar o envio do seu próprio produto; para quem trabalha com QA e precisa separar relatório de semente de recebimento real; e para quem desenvolve sozinho e quer evitar testes duplicados quando uma chamada falha e é repetida.
Última atualização: 20 de novembro de 2026. Os detalhes da API e do relatório foram conferidos na documentação oficial do Send API, nas instruções para executar um teste Inbox Placement pelo Send API e no guia oficial de testes com sementes. Confira essas referências novamente antes de alterar o pipeline, pois a documentação pode mudar.
Antes do CI: escolha o que você quer provar
Um teste de e-mail pode verificar etapas diferentes. Se você não decidir qual evidência espera do job, é fácil considerar sucesso uma resposta de envio que não confirma a entrega que importa para o produto.
| Objetivo do teste | O que executar | O que o resultado permite concluir |
|---|---|---|
| Validar a lógica do aplicativo | Testar a geração do conteúdo, destinatário e chamada de envio, sem depender de uma caixa-semente | A aplicação preparou e enviou a solicitação conforme esperado; não prova posicionamento na caixa de entrada |
| Observar posicionamento em sementes | Enviar pelo Mailgun Send API com o:inbox-placement-test-key |
O teste associado produziu dados sobre as caixas-semente configuradas; não representa todos os provedores nem todos os usuários |
| Validar o fluxo de ponta a ponta | Além do teste de sementes, enviar a um endereço controlado e verificar a mensagem e o link | O endereço controlado recebeu conteúdo utilizável para aquele cenário; isso não garante posicionamento universal |
Antes de configurar o job, confirme que o recurso Inbox Placement está habilitado para a conta e que o envio usa um domínio e um ambiente que você controla ou está autorizado a testar. O parâmetro não transforma um envio comum em garantia de entrega para todos os destinatários: ele associa aquela solicitação ao teste de posicionamento definido pela Mailgun. A referência do parâmetro no Send API é a fonte para conferir o nome e o formato aceito.
Defina também o critério de sucesso do pipeline. Se a entrega de um link de ativação é requisito do produto, o relatório de sementes pode ser uma verificação adicional, mas não deve ser o único bloqueio de qualidade. Se a meta é observar mudanças de posicionamento em uma campanha de teste autorizada, então o relatório pode ser a evidência principal dessa etapa, sem substituir os testes da aplicação.
Preparação: vincule a solicitação à execução
O parâmetro o:inbox-placement-test-key deve acompanhar a solicitação normal de envio. A mensagem é enviada à lista de sementes associada ao teste; portanto, você não precisa tratar o relatório como se fosse a confirmação de que um destinatário final recebeu a mensagem. Consulte a documentação da Mailgun sobre a solicitação de envio para Inbox Placement para verificar os requisitos atuais do recurso.
No CI, registre uma identificação legível da execução junto com a chave e o resultado da chamada. Você pode montar a identificação a partir do nome do pipeline, da revisão testada e do tipo de mensagem, desde que ela não contenha segredos nem dados pessoais. Mantenha a chave em uma variável protegida do job se ela não puder aparecer nos logs; a chave da API da conta também deve permanecer em um segredo, nunca no código versionado.
Um exemplo esquemático com curl:
curl --user "api:${MAILGUN_API_KEY}" \
--form "from=${MAIL_FROM}" \
--form "to=${QA_RECIPIENT}" \
--form "subject=${TEST_SUBJECT}" \
--form "text=${TEST_BODY}" \
--form "o:inbox-placement-test-key=${INBOX_PLACEMENT_TEST_KEY}" \
"https://api.mailgun.net/v3/${MAILGUN_DOMAIN}/messages"
Use esse formato apenas como ponto de partida: MAILGUN_DOMAIN, remetente, destinatário e conteúdo devem corresponder à configuração autorizada do seu ambiente. A requisição envia a mensagem pelo endpoint normal e associa o teste usando o campo específico; ela não deve ser montada como um envio separado de uma campanha real para contatos sem consentimento.
Guarde pelo menos três evidências distintas no log do job: a identificação da execução, o resultado HTTP e o corpo da resposta do envio, removendo credenciais e informações pessoais desnecessárias. Não rotule uma resposta bem-sucedida do envio como “relatório pronto” ou “e-mail recebido”. Ela confirma a resposta à solicitação; o relatório e a recepção controlada são etapas posteriores.
Execução e retentativas: preserve a identidade do teste
A chave funciona como um identificador de idempotência para o teste. Segundo a orientação oficial para executar Inbox Placement pelo Send API, reutilizar a mesma chave dentro de 7 dias não cria um novo teste. A documentação também informa que há um limite para a quantidade de chaves armazenadas na conta; como não se deve presumir um número que a referência não especifica aqui, confira a orientação atual da Mailgun para sua conta.
Isso ajuda a separar uma repetição causada por falha de rede de uma nova rodada intencional. Se o CI não recebeu uma resposta clara e repete a mesma operação, mantenha a chave da execução lógica original. Assim, a retentativa não pede à Mailgun que crie um teste diferente apenas porque o cliente não conseguiu confirmar o resultado da primeira chamada.
Quando você iniciar deliberadamente uma nova rodada — por exemplo, após alterar o template e querer comparar a nova versão — gere uma chave nova e associe-a a essa execução. Não crie uma chave aleatória a cada tentativa automática: isso enfraquece a idempotência e pode consumir o limite de chaves armazenadas sem produzir uma nova evidência útil.
Na prática, separe dois conceitos no seu pipeline:
- Retentativa técnica: mesma execução lógica, mesma chave, mesma finalidade.
- Nova rodada de avaliação: nova execução intencional, nova chave e identificação que a diferencie nos logs.
- Reexecução manual: decida antes se você quer recuperar o resultado da rodada anterior ou criar um teste novo; não deixe essa escolha acontecer por acidente em um script de retry.
O principal benefício dessa estratégia é reduzir testes duplicados e tornar a trilha de auditoria compreensível. A desvantagem é que uma chave reutilizada não representa uma avaliação nova; se você mudou o conteúdo e quer observar o efeito dessa mudança, precisa iniciar outra rodada de forma explícita.
Diagnóstico: relatório ausente não significa e-mail perdido
Se o relatório não aparecer, comece pela execução, não pela conclusão de que a mensagem foi descartada. Verifique se a chave já foi usada dentro da janela de 7 dias e se a conta pode ter atingido o limite de chaves armazenadas. Depois, confira se a solicitação realmente incluiu o:inbox-placement-test-key, se o domínio e o recurso são os esperados e se a resposta do Send API corresponde à execução registrada.
Em seguida, confirme o estado do envio para a lista de sementes. A orientação oficial sobre como enviar um teste de sementes diferencia mensagens ainda não recebidas pelas sementes de uma conclusão de falha definitiva. Um estado Missing deve ser interpretado segundo a definição e os limites de espera descritos na documentação vigente; não invente um prazo no pipeline nem transforme a ausência temporária em falha imediata sem conferir a regra oficial.
O guia de estados e relatórios do Inbox Placement deve orientar a consulta do resultado e a leitura de cada estado. Armazene o identificador da chamada, o horário da execução e a referência ao teste para conseguir correlacionar o relatório depois. Se a API responder com sucesso, mas o relatório ainda não estiver disponível, mantenha essas etapas como eventos separados no CI em vez de registrar uma única condição genérica chamada “e-mail OK”.
Uma ocorrência típica ajuda a enxergar o problema: o job envia uma mensagem, perde a conexão antes de registrar a resposta e repete a solicitação. Se a segunda chamada usa uma chave diferente, você pode acabar com duas identidades de teste para o que pretendia tratar como uma única execução. Se a chave é a mesma, mas o relatório não aparece, a investigação continua: confira a validade de uso, a configuração da conta, a solicitação registrada e o estado das sementes. Nenhum desses sinais, isoladamente, prova que um usuário real recebeu ou deixou de receber a mensagem.
Aceitação: acompanhe a linha do tempo até a caixa controlada
Uma implementação confiável deixa claro o que cada etapa prova. Registre a chamada do CI, a resposta do Mailgun Send API, o resultado da consulta ao relatório Inbox Placement e, quando o objetivo exigir, a mensagem observada em um endereço controlado. A sequência impede que uma evidência parcial seja promovida a uma conclusão de negócio.
A lista de sementes é um conjunto de ambientes de teste, não uma amostra de todos os destinatários possíveis. O resultado depende da configuração do teste e das sementes correspondentes; não prova que uma mensagem de cadastro foi renderizada, que o link de verificação abre ou que o sistema alterou o estado da conta depois do clique.
Para validar o fluxo de cadastro, crie uma verificação adicional no ambiente de teste: envie a mensagem para uma caixa controlada, confirme que o conteúdo esperado chegou e teste o link com os dados de teste apropriados. Separe essa verificação da leitura do relatório. Se você precisar apenas medir o comportamento das sementes, não marque a caixa controlada como critério obrigatório; se o e-mail precisa habilitar uma ação do usuário, trate a validação ponta a ponta como parte da aceitação.
Isso também evita misturar dados de produção com testes. Use destinatários e conteúdo sintéticos no ambiente autorizado, sem incluir informações pessoais reais nos assuntos, corpos ou logs. Se a equipe está decidindo entre uma caixa temporária e um endereço duradouro para esse tipo de teste, o guia sobre diferenças entre e-mail descartável e alias ajuda a comparar opções sem confundir recebimento controlado com posicionamento em sementes. Para mensagens ligadas a contas importantes ou que exijam recuperação posterior, prefira um endereço sob controle contínuo, não uma caixa temporária.
Manutenção: evite falsos positivos no pipeline
A automação deve falhar quando a etapa que você realmente exige falha, e não quando um relatório apenas ainda não está pronto. Modele estados separados para “solicitação aceita”, “relatório disponível”, “resultado das sementes interpretado” e “mensagem recebida na caixa controlada”. Essa divisão deixa visível em qual etapa a execução parou e permite ajustar a política de retentativa sem reenviar indiscriminadamente.
Também vale tratar o teste de posicionamento como uma verificação monitorada, não como um substituto para testes unitários ou de integração do aplicativo. O Send API pode confirmar que a solicitação foi processada, mas não verifica por si só se sua lógica escolheu o destinatário correto, se o token do link corresponde à conta ou se a página de confirmação atualizou o estado esperado.
Antes de liberar alterações no pipeline, confira estas decisões:
- O recurso está habilitado na conta e o domínio é seu ou autorizado?
- O envio do job inclui a chave correta e uma identificação rastreável?
- As retentativas reutilizam a chave da mesma execução?
- Uma nova rodada intencional recebe uma nova chave?
- Os logs distinguem resposta de envio, relatório de sementes e recebimento controlado?
- A regra para
Missingsegue a definição atual da documentação, sem prazo inventado? - A aceitação corresponde ao risco do recurso: posicionamento, recebimento ou fluxo completo?
Se você precisa de uma caixa separada para observar o e-mail do seu próprio produto, o Mailtock pode ser uma opção para essa verificação controlada: consulte o guia de privacidade e uso de e-mail temporário e avalie se o tipo de recebimento atende ao seu cenário. Isso é independente do teste de sementes da Mailgun e não garante entrega. Para uma execução pontual de desenvolvimento, uma caixa temporária pode evitar expor seu endereço principal; para contas importantes, recuperação de acesso ou mensagens que exigem resposta e histórico duradouro, use um endereço permanente.
Este artigo oferece orientações para organizar e-mails de compras e não substitui as informações da loja sobre pedidos, cancelamento de inscrições ou privacidade. Consulte as regras do serviço correspondente para saber onde fazer solicitações e quais são os prazos de atendimento.