Envio de e-mail usando a API do Mailgun em PHP

Este é um post de convidado de Mihály Sáróy, desenvolvedor na EDMdesigner.

Já faz um tempo desde o lançamento do SDK do Mailgun em PHP e vimos muitas mudanças: novas funcionalidades, novas integrações criadas sobre ele, novos endpoints de API… mas a base do PHP continua a mesma. Como foi o primeiro SDK para a API do Mailgun, ele teve tempo para amadurecer e passar por iterações que facilitam o seu uso, o que percebemos quando o testamos.

Neste post, vamos mostrar como você pode implementar a API do Mailgun usando PHP com PEAR.

Vamos começar este guia dizendo que o e-mail transacional está em toda parte, e é importante fazermos isso direito. Não fazer o e-mail funcionar corretamente pode significar perda de receita para a sua empresa e, em geral, cria uma experiência desagradável para os clientes.

Como profissional de desenvolvimento, você sempre busca encontrar a maneira mais simples (eficiente em termos de tempo) e poderosa de resolver um problema. Geralmente, você consegue isso cumprindo duas condições:

1. Usando bibliotecas externas que se aplicam à sua solução.
2. Projetando aplicativos escaláveis.

Não há necessidade de explicar a primeira condição: você não começaria a escrever um sistema operacional antes da programação de um aplicativo, certo? Ao longo do post, veremos como usar pacotes pré-escritos para enviar e-mails. Mas agora, vamos ao segundo ponto: continue lendo. 

Para um design escalável, é aqui que você procura serviços como o Mailgun. Você pode esperar uma solução rica em recursos que atenda aos requisitos para envio de e-mails em alto volume.

Se você se importa com a entrega (e deveria), o Mailgun oferece alta confiabilidade, pois foi projetado para lidar muito bem com e-mails transacionais. Você pode configurar vários domínios e escolher se deseja compartilhar IPs ou construir sua própria reputação. Para proteger os cabeçalhos dos seus e-mails, o Mailgun requer que DKIM e SPF sejam adicionados à conta e que passem pelas verificações no nível de autenticação e alinhamento. Todas essas coisas trabalham juntas para ajudar você com a entrega de e-mails.

Agora a melhor parte: configurar um script wrapper em PHP para o Mailgun. Primeiro, usaremos o gerenciador de pacotes e, depois, veremos exemplos de como aplicá-lo.

O PEAR é uma iniciativa voltada para a comunidade que nos permite reutilizar componentes de programação em PHP, enquanto o código dependente também é adicionado e mantido.

Primeiro, você precisará do PHP e do gerenciador de pacotes para continuar. A melhor forma de instalá-los é pelo Debian Advanced Package Manager (APT) se você estiver usando Linux.

Embora o PEAR seja uma solução mais antiga, ainda é amplamente utilizado e é a sigla para PHP Extension and Application Repository. Com base na versão do PHP instalada, você provavelmente já tem o PEAR disponível. Você pode verificar executando o comando pear sem argumentos. Se você receber um aviso de que seu sistema não o possui, basta executar: sudo apt install php-pear. Agora, estamos prontos para instalar código PHP de terceiros com o PEAR.

Se você acompanhar este artigo fazendo a programação junto conosco, este é o momento em que você deve abrir sua conta do Mailgun para ter acesso à API. Se você tiver dúvidas, confira estas dicas iniciais.

Os passos com o PEAR se aplicam da seguinte forma:

1. Instalação de dependências do projeto e inclusão dos pacotes exigindo a classe principal ou o script vendor/autoloader.php
2. Fornecer credenciais relacionadas à API, como sua chave de API e informações de domínio 
3. Instanciar a classe/cliente Mail
4. Fazer a chamada de função para enviar o(s) e-mail(s)

Simples, não é?

Podemos instalar o pacote Mail digitando sudo pear install Mail usando o comando apropriado. Após a conclusão da instalação, o próximo passo é incluir isso em um arquivo de script no diretório do seu projeto:

require_once "Mail.php";

Economize tempo e faça como nosso modelo sugere, em seguida, forneça as variáveis específicas da API. 

Ao acessar o seu painel da API, você pode encontrar essas informações necessárias na aba de domínio:

Precisamos das variáveis de host, account user e password, e da port para usar:

Usamos a conexão SMTP para enviar e-mails pela nossa conta do Mailgun.

Reunimos os parâmetros acima em um array e instanciamos a classe Mail com isso:

O passo final é chamar o método send() da classe Mail e estamos prontos:

Aqui, a variável $to guarda o valor do endereço do destinatário, enquanto a variável $headers é um array, contendo campos adicionais para a entrega.

Neste momento, você pode querer verificar o código final completo:

Você pode baixar o código-fonte completo aqui.

Seguindo em frente, se você configurou tudo, pode tentar executar o script: php mailer.php.

Você o executa e recebe um terrível rastreamento de erro! Examine-o de perto:

PHP Fatal error: Uncaught Error: Class 'Net_SMTP' not found in /usr/share/php/Mail/smtp>php:366.

Isso significa que esquecemos de adicionar outra dependência do projeto que é necessária para usar o PEAR Mail. Execute sudo pear install Net_SMTP e tente novamente!

A saída é:

Mensagem enviada com sucesso!

Se você acompanhou até aqui, então sua mensagem deve ter chegado à caixa de correio especificada, e eu estou aplaudindo você. Parabéns! 

A função nativa mail() do PHP pode enviar mensagens do seu aplicativo, mas ela vem com algumas limitações. Como depende da configuração de e-mail local do seu servidor, os e-mails enviados dessa maneira costumam cair em filtros de spam ou são totalmente bloqueados. Também faltam recursos modernos essenciais, como rastreamento, análises e recursos confiáveis de entregabilidade. De forma mais crítica, implementações ingênuas podem expor você a ataques de injeção de cabeçalho. Em resumo, a função mail() funciona em uma emergência, mas para e-mails de produção você vai querer uma API dedicada como o SDK em PHP do Mailgun. 

• Entregabilidade: as mensagens dependem da configuração de e-mail local do seu servidor, que muitas vezes carece de alinhamento adequado de SPF, DKIM e DMARC. Isso diminui a reputação do remetente e reduz a entrega na caixa de entrada. 
• Risco de spam: e-mails de servidores da web são frequentemente sinalizados ou rejeitados por filtros que não confiam em IPs de servidores genéricos e na falta de autenticação. 
• Sem autenticação SMTP: a função mail() não oferece suporte nativo a SMTP autenticado. Você deve configurar manualmente ou usar outra biblioteca para enviar por meio de uma retransmissão SMTP adequada. 
• Sem rastreamento ou análises: não há uma maneira integrada de rastrear aberturas, cliques, devoluções ou reclamações e nenhum webhook de evento para monitoramento programático. 

Para uma entrega, autenticação e análises confiáveis, use um serviço dedicado como a API do Mailgun em PHP. 

Vimos o script de exemplo para começar a usar o Mailgun com o gerenciador de pacotes PEAR, e criamos scripts PHP para enviar um e-mail com SMTP e a API HTTP. A incorporação de testes adequados garante que as funções de entrega do seu e-mail funcionem conforme o esperado. Mas há outras opções que você poderia usar se o PEAR não for sua primeira escolha. Alternativas como o SendGrid permitem replicar o mesmo resultado usando o Composer, e o Mailgun já entrou em detalhes sobre isso anteriormente no blog. Ou, para obter instruções mais detalhadas, confira nosso tutorial sobre a implementação da API do Mailgun com PHP. 

E, claro, se você deseja aprimorar as suas skills com PHP, estes são alguns dos meus recursos favoritos que eu recomendaria para enviar e-mail com PHP e lidar com e-mails em HTML em geral. 

Autor: Mailgun Community Stories from the Mailgun community