Como testar as APIs de e-mail do Sinch Mailgun usando o Postman

Sinch Mailgun é um serviço de e-mail voltado para a equipe de desenvolvimento que oferece uma API RESTful para enviar, receber e rastrear mensagens em grande escala. Para testar esses endpoints ou solucionar problemas de uma integração sem programação, você pode usar o Postman, uma ferramenta popular de testes de API. Recentemente, em outro artigo, falamos sobre como integrar o Sinch Mailgun com o Postman. Neste artigo, vamos focar mais no uso.

Postman oferece uma maneira rápida e visual de testar APIs. Isso o torna ideal para depuração e aprendizado, ou para validar credenciais sem precisar de programação. Neste guia, você usará o Postman para testar e solucionar problemas da API de e-mail do Sinch Mailgun.

Antes de começar, você precisa do seguinte:

Uma conta do Sinch Mailgun: você precisa de um domínio ativo ou pode usar o domínio sandbox. Você também precisa de uma chave de API.
O aplicativo do Postman: Download e instalar o aplicativo do Postman. Familiaridade básica com solicitações e ambientes é útil, mas não obrigatória.

Para começar, importe a coleção e o ambiente do Sinch Mailgun para poder começar a testar imediatamente. No Postman, clique no botão “Import” e use o link da coleção para adicionar a coleção do Sinch Mailgun:

Como alternativa, faça um fork da API do Sinch Mailgun na Public API Network. Certifique-se de incluir o ambiente correspondente do Sinch Mailgun:

Em seguida, você precisa configurar as variáveis de ambiente. Abra o ambiente do Sinch Mailgun selecionando o ícone de engrenagem (“Gear”) e, em seguida, “Manage Environments > Mailgun”. Insira os seus dados exatamente como mostrado:

Deixe o token em branco. A coleção o gera automaticamente a partir de sua API_KEY usando um script de pré-solicitação e lida com a autenticação para você. Certifique-se de selecionar “Sinch Mailgun” no menu suspenso de ambientes:

Para verificar a configuração, na pasta “Domains” da coleção, abra “Get domains” e clique em “Send”. Uma resposta bem-sucedida é parecida com esta:

                                

                                    {
  "total_count": 1,
  "items": [
    {
      "created_at": "Sat, 06 Jan 2024 10:27:15 GMT",
      "id": "65992b03de",
      "is_disabled": false,
      "name": "sandbox93abbcf3db544a.mailgun.org",
      "state": "active"
    }
  ]
}
                                
                            

Se você vir isso, o seu ambiente do Postman está pronto. Caso contrário, verifique a sua chave de API e o valor de mydomain.

Agora que a configuração está pronta, vamos explorar alguns cenários comuns da API do Sinch Mailgun. Abordaremos alguns conceitos básicos, como o envio de um e-mail e a recuperação de listas de e-mails. Depois, você aprenderá a validar endereços de e-mail e buscar logs de eventos.

O teste de entrega de e-mail confirma que a sua chave de API e domínio estão configurados corretamente. Na coleção da API do Sinch Mailgun do Postman, abra a solicitação “Send message” em “Messages”.

A solicitação usa as suas variáveis de ambiente para formar a URL:
POST https://api.mailgun.net/v3/{{mydomain}}/messages
O Postman inclui um cabeçalho Authorization: Basic {{token}}. Isso codifica a sua chave de API.
Para definir os dados do formulário, alterne para a aba “Body” e escolha “form-data”. No mínimo, você precisa do seguinte:
from=postmaster@{{mydomain}}

to=seue-mail@example.com

subject=Olá do Mailgun via Postman

text=Este é um e-mail de teste enviado usando o Postman

Esses campos garantem que a mensagem seja endereçada corretamente, contenha conteúdo e confirmam que o seu domínio e chave de API estão configurados adequadamente. Se você estiver usando um domínio de sandbox, o endereço to deve ser autorizado no painel do Sinch Mailgun. Para testar sem a entrega real, adicione o seguinte:
o:testmode=yes
Agora, clique em “Send”. Uma resposta bem-sucedida é parecida com esta:
{ "id": "", "message": "Queued. Thank you." }
O id é o identificador da sua mensagem. Você pode usar esse ID com a Events API para rastrear o status de entrega.

O Sinch Mailgun permite que você agrupe os destinatários em endereços de listas de e-mails, como newsletter@seudominio.com. Você pode usar o Postman para confirmar as suas listas e os respectivos membros.
Para listar todas as listas de e-mails, abra “Get mailing lists” na pasta “Mailing Lists” e envie uma solicitação GET para o seguinte:
{{BASE_URL}}/lists
Uma resposta válida é parecida com esta:

                                

                                    {
  "total_count": 1,
  "items": [
    {
      "address": "developers@mydomain.net",
      "name": "Developers",
      "description": "Describe the mailing list",
      "access_level": "readonly",
      "members_count": 2,
      "created_at": "Tue, 25 June 2025 20:50:27 -0000"
    }
  ]
}
                                
                            

O array items contém o endereço de e-mail, o nome, o nível de acesso e a contagem de assinantes de cada lista. Um array vazio indica que não há listas de e-mails. Mais informações sobre esse endpoint estão disponíveis na documentação da API do Sinch Mailgun.
Para listar os membros de uma lista de e-mails específica, duplique a solicitação anterior no Postman ou use “Get list members”. Em seguida, ajuste a URL para o seguinte:
{{BASE_URL}}/lists/newsletter@seudominio.com/members
Isso retorna uma resposta mostrando o endereço de e-mail de cada membro e o status de sua assinatura:

                                

                                    {
  "total_count": 2,
  "items": [
    {
      "address": "user1@example.com",
      "name": "User One",
      "subscribed": true
    },
    {
      "address": "user2@example.com",
      "name": "User Two",
      "subscribed": true
    }
  ]
}
                                
                            

Isso verifica se as suas listas de e-mails e assinantes estão configurados corretamente e, por sua vez, ajuda a confirmar se as listas estão preenchidas antes do envio de campanhas.

O Sinch Mailgun API de validação de e-mail permite verificar se um endereço é real antes de enviar algo para ele. Isso reduz as devoluções e mantém as suas listas limpas. Nesta seção, você focará na validação de endereço único, mas a validação em massa com o upload de um CSV ou JSON também é possível.
Para criar a solicitação, inicie uma nova solicitação GET no Postman e insira o seguinte:
https://api.mailgun.net/v4/address/validate?address=test@example.com

Clique em “Send”. Para um endereço válido, você vê o seguinte:

                                

                                    {
  "address": "existingemail@realdomain.com",
  "is_disposable_address": false,
  "is_role_address": false,
  "reason": [],
  "result": "deliverable",
  "risk": "low"
}
                                
                            

                                

                                    echo "test";
                                
                            

Se a caixa de correio não existir, você verá isto:

                                

                                    {
  "address": "nonexistentemail@realdomain.com",
  "is_disposable_address": false,
  "is_role_address": false,
  "reason": ["mailbox_does_not_exist"],
  "result": "undeliverable",
  "risk": "high"
}

                                
                            

O campo result mostra se o Sinch Mailgun considera o endereço entregável. O array reason explica falhas e riscos, e ajuda a filtrar e-mails inválidos para reduzir as taxas de devolução.
Para verificar vários endereços de uma só vez, o Sinch Mailgun tem suporte a um endpoint de validação em massa que aceita o upload de arquivos CSV ou JSON; consulte a documentação oficial para obter mais informações.

Após enviar um e-mail, você pode confirmar o que aconteceu. O Sinch Mailgun Events API ajuda a rastrear como a mensagem foi processada. Você pode usá-la para ver se um e-mail foi accepted, delivered, opened, bounced ou rejected.
Abra “Get Events” na pasta “Events”. Certifique-se de que o seu ambiente do Sinch Mailgun esteja ativo, em seguida, clique em “Send”. O endpoint de solicitação deve ser parecido com este:
GET /v3/{{mydomain}}/events
A resposta contém um array items de objetos de evento. Cada item no array items contém detalhes sobre um evento específico. Aqui está um exemplo de um evento rejeitado de um domínio de sandbox:

                                

                                    {
  "event": "rejected",
  "id": "OMTXD3-sSmKIQa1gSKkYVA",
  "reject": {
    "reason": "Sandbox subdomains are for test purposes only. Please add your own domain...",
    "description": ""
  },
  "message": {
    "headers": {
      "to": "joan@example.org",
      "from": "john@sandbox12345.mailgun.org",
      "subject": "Test Subject",
      "message-id": "20180622220256.1.B31A451A2E5422BB@sandbox12345.mailgun.org"
    },
  }
}
                                
                            

Essa resposta mostra que a mensagem foi rejeitada porque foi enviada a um destinatário não autorizado usando um domínio de sandbox. Você também vê outros eventos:
"accepted": o Sinch Mailgun recebeu e colocou a mensagem na fila.
"delivered": a mensagem foi entregue ao servidor dos destinatários.
"failed": falha na entrega devido a um erro de servidor, problema de DNS ou outro problema.
"opened": o cliente de e-mail dos destinatários disparou o pixel de rastreamento invisível do Sinch Mailgun.
"bounced" – o servidor dos destinatários rejeitou a mensagem. Verifique o campo severity para distinguir as devoluções soft (temporárias) das devoluções hard (permanentes).

Mais detalhes podem ser encontrados na documentação de referência de eventos do Sinch Mailgun.

Para facilitar a inspeção dos eventos, você pode filtrá-los. O Postman permite que você adicione parâmetros de consulta na aba “Params”. Aqui estão algumas opções úteis:
event=delivered retorna apenas as mensagens entregues.
message-id= filtra por uma mensagem específica. Você pode encontrar esse ID na resposta da solicitação “Send message”.

Por exemplo, depois de enviar um e-mail de teste, copie o seu id da resposta de envio. Em seguida, filtre os eventos assim:
GET /v3/{{mydomain}}/events?message-id=
Estas etapas ajudam a rastrear o status de cada mensagem. Para obter uma lista completa dos tipos de eventos e campos, confira a documentação de referência de eventos do Sinch Mailgun. Essas análises são especialmente importantes ao usar soluções de e-mail em massa, como o Sinch Mailgun, pois ajudam a monitorar a entregabilidade e a identificar problemas precocemente. Isso é fundamental para garantir que o seu domínio mantenha uma forte reputação do remetente.

Até agora, você usou o Postman para testar a API do Sinch Mailgun manualmente. Isso é útil para verificações rápidas, mas o Postman também tem suporte à automação usando scripts de teste baseados em JavaScript. Eles são executados após cada solicitação e podem ser usados para validar respostas ou passar valores entre as solicitações. O Postman inclui Chai para BDD-style asserções.
Esse recurso permite a construção de suítes de testes que se comportam como fluxos de trabalho leves de QA. A automação de testes ajuda a validar os fluxos de trabalho de e-mail sem esforço manual.

Se você deseja testar o endpoint “Send message”, é possível usar a aba “Scripts” do Postman para verificar se a solicitação foi bem-sucedida:

Adicione o seguinte script na aba “Scripts”:
pm.test(\"Status code is 200\", function () { pm.response.to.have.status(200); }); pm.test(\"Sinch Mailgun queued the message successfully\", function () { const resData = pm.response.json(); pm.expect(resData.message).to.eql(\"Queued. Thank you."); });

Esse script verifica se há um status HTTP bem-sucedido e confirma que a resposta do Sinch Mailgun contém a mensagem esperada. Se um dos testes falhar, o Postman marcará a solicitação como falha no painel de resultados do teste.

Você pode encadear solicitações salvando valores de uma resposta e reutilizando-os em outra. Por exemplo, depois de enviar um e-mail, você pode querer capturar o seu id e usá-lo para consultar a Events API.
Na solicitação “Send Message”, na aba “Tests”, adicione o seguinte:
const resData = pm.response.json(); pm.environment.set(\"sent_message_id\", resData.id);
Agora, na solicitação “Get Events”, adicione um parâmetro de consulta:
message-id={{sent_message_id}}
Ao executar a coleção, o Postman substitui automaticamente o ID da mensagem salvo. Você também pode adicionar testes para verificar a resposta:
pm.test("At least one event is present for the sent message", function () { const events = pm.response.json().items; pm.expect(events.length).to.be.above(0); });
Esse fluxo de trabalho é especialmente útil para verificar os resultados de entrega durante os testes de regressão.

Os scripts do Postman estendem os seus testes manuais em fluxos de trabalho repetíveis sem a necessidade de um sistema completo de CI. Ao escrever asserções na aba “Scripts”, você pode verificar respostas automaticamente e passar dados entre as solicitações.
Quando quiser automatizar tudo, exporte a coleção e execute-a com o Newman CLI como parte de um job simples de build ou smoke test. Essa configuração é ideal para o controle de qualidade inicial (QA), prototipagem rápida e compartilhamento de verificações de API com a sua equipe. Para obter mais padrões e exemplos de scripts, confira o guia Test Examples do Postman.

O teste do Sinch Mailgun no Postman pode, às vezes, gerar erros. Aqui está uma lista resumida dos problemas comuns e como resolvê-los:

Erros de autenticação 401/403: verifique se você está usando a chave de API privada e não a chave pública de validação. O Postman deve usar a autenticação básica HTTP com api como nome de usuário e a sua chave como senha. Em caso de dúvida, copie-a novamente do seu painel do Sinch Mailgun.

400 Bad Request: esse problema geralmente significa um parâmetro incorreto ou ausente. O Sinch Mailgun costuma informar o que deu errado na resposta. Verifique os campos obrigatórios, como to, from e subject, e certifique-se de que não haja erros de digitação.

404 Not Found: esse erro é mais provavelmente causado por um domínio incorreto ou ausente na URL (ex.: {{mydomain}} está em branco ou errado). Também há a possibilidade de você ter feito uma solicitação para um endpoint de API inválido. Certifique-se de verificar se o endpoint e a sua variável de ambiente correspondem a um domínio válido na sua conta do Sinch Mailgun.

429 Too Many Requests: você está atingindo um limite de taxa. Desacelere as suas solicitações ou aguarde a redefinição da sua cota. Contas gratuitas ou não verificadas têm limites mais baixos, especialmente na validação e no envio. A limitação de taxa (também conhecida como throttling) ajuda a evitar abusos e garante o uso justo dos recursos para toda a base de usuários. O Sinch Mailgun impõe isso para manter o serviço confiável.

5xx Server Errors: esses são problemas do lado do Sinch Mailgun. Aguarde e tente novamente mais tarde. Se persistir, consulte a página de “Status” do Sinch Mailgun ou entre em contato com o suporte.

Leitura de respostas: as respostas JSON do Sinch Mailgun podem ser prolixas. Use a visualização “raw” ou “Pretty” do Postman para explorar campos profundamente aninhados. Você também pode usar console.log() na aba “Tests” para inspecionar os dados, da seguinte maneira:
const events = pm.response.json().items; events.forEach((e) => console.log(e.event));
Em caso de dúvida, pesquise a mensagem de erro exata na documentação ou nos fóruns do Sinch Mailgun. Os códigos de erro são descritivos e a solução geralmente está a apenas um clique de distância.

O Postman oferece uma maneira prática de interagir com a API do Sinch Mailgun. Neste guia, você cobriu alguns dos usos mais comuns – o envio de e-mails, a recuperação de listas de e-mails, a validação de endereços de e-mail e a inspeção de eventos.
Para profissionais de engenharia e equipes de QA, o Postman é uma ferramenta de diagnóstico confiável que facilita o teste de credenciais e a replicação do comportamento de produção. Os seus recursos de script e suporte a ambientes flexíveis integram-se perfeitamente aos fluxos de trabalho existentes. Você pode usá-lo para confirmar detalhes de integração antes da implantação e, novamente, quando as coisas dão errado. É uma forma rápida e confiável de manter o controle sobre os seus fluxos de trabalho de e-mail.