Como enviar e-mail com PHP usando Twilio SendGrid e Mezzio

Publicados: 2021-03-24

O e-mail é uma ferramenta de comunicação tão importante como sempre. Para ajudá-lo a aproveitar melhor o e-mail, mostrarei como enviar e-mail usando o framework Mezzio do PHP e a API do Twilio SendGrid.

Especificamente, você aprenderá a enviar e-mails com corpos de texto simples e HTML, e isso inclui um anexo em PDF. Você também aprenderá a usar a funcionalidade de modelos transacionais do Twilio SendGrid para simplificar a criação de corpos de e-mail tanto pela equipe de desenvolvimento quanto por qualquer outra equipe em sua organização.

Parece bom? Vamos começar.

Visão geral rápida do aplicativo

Como forma de tornar este tutorial mais significativo, finja que o código que vamos escrever é parte de uma loja de comércio eletrônico fictícia construída com Mezzio, chamada The Little PHP Shop — especificamente, a parte imediatamente após o cliente fazer uma compra. Nesse ponto do fluxo do usuário, o cliente recebe um e-mail agradecendo a compra e inclui uma fatura em PDF para seus registros.

Vamos criar uma classe Handler para enviar o e-mail pós-compra, que receberá os detalhes da compra de um pedido concluído pelo cliente. Com essas informações de compra, a classe Handler usará várias classes na API PHP do SendGrid para construir e enviar o e-mail de confirmação de compra.

Destes, os mais importantes são “SendGrid\Mail\Mail” e “\SendGrid”. “SendGrid\Mail\Mail” é o objeto que armazena todas as propriedades de uma mensagem de email que enviaremos através do Twilio SendGrid. O objeto “SendGrid” forma a camada de transporte, facilitando o envio de emails através do Twilio SendGrid.

Pré-requisitos

Para concluir este tutorial, você precisará das 4 coisas a seguir em seu ambiente de desenvolvimento local:

  1. Conta Twilio SendGrid
  2. PHP 7.4 com as extensões SSL cURL , mbstring e O pen instaladas e habilitadas
  3. Compositor instalado globalmente
  4. ondulação

Montar o aplicativo Mezzio

Primeiro precisamos criar o aplicativo base. Para fazer isso, vamos, como sempre, usar o Mezzio Skeleton para fazer isso por nós. Assim que montarmos o scaffold do aplicativo base, mudaremos para o diretório do projeto recém-criado. Em seguida, execute os seguintes comandos em seu terminal, seguindo os prompts do primeiro:

Instale as dependências necessárias

Com o projeto scaffolded, precisamos adicionar 3 dependências adicionais para concluir o projeto. Estes são:

  • Biblioteca de API PHP do Twilio SendGrid para interagir com a API Twilio SendGrid
  • Cliente HTTP PHP para enviar solicitações HTTP
  • PHP Dotenv para armazenar e recuperar variáveis ​​de ambiente

Para instalá-los, execute o seguinte comando no seu terminal:

Inicializar PHP Dotenv

Com as dependências instaladas, carregamos o PHP Dotenv para que ele leia as variáveis ​​definidas em “.env” e as disponibilize para o PHP como variáveis ​​de ambiente. Para fazer isso, insira o seguinte código em “public/index.php”, logo após “require vendor/autoload.php”.

Adicione os detalhes da sua conta do Twilio SendGrid

Agora você precisa fornecer ao aplicativo sua chave de API do SendGrid. Para isso, após fazer login no Twilio SendGrid , navegue até “Settings -> API Keys . " Uma vez lá:

  1. Clique em “ Criar chave de API ” para criar uma chave de API
  2. Dê um nome à nova chave de API, aceite a permissão de chave de API padrão de “ Acesso total ” e clique em “ Criar e visualizar ”

Com a chave de API criada, clique e copie a chave, depois clique em “ Concluído . ”

Depois disso, adicione mais 2 chaves ao arquivo: “SENDGRID_DEFAULT_SENDER_ADDRESS” e “SENDGRID_DEFAULT_SENDER_NAME”. Como os nomes indicam, esses são o endereço de e-mail e o nome que usaremos para todos os e-mails enviados de nosso aplicativo, a menos que sejam substituídos.

Observação: Para fazer isso, em Sender Authentication , certifique-se de que diz “Verified” na tabela “Single Sender Verification”.

Definir detalhes de configuração de correio do aplicativo

Além da chave da API Twilio SendGrid, vamos armazenar algumas outras configurações globais de correio. Especificamente, definiremos um endereço de e-mail de e uma resposta para e um nome que usaremos em cada mensagem de e-mail. Dessa forma, não precisamos configurá-los toda vez.

Também vamos criar 2 modelos de corpo de e-mail: um para e-mails de texto simples e outro para e-mails em HTML. Para isso, em “config/autoload” crie um novo arquivo chamado “mail.global.php” e nele adicione o seguinte código.

Criar uma classe para instanciar um objeto de email

Com os principais detalhes de configuração do aplicativo definidos, vamos agora criar uma classe que instanciará um objeto de email básico com as propriedades padrão definidas. Para isso, em um novo diretório, “src/App/src/Mailer”, crie um novo arquivo chamado “SendGridMailMessageFactory.php” e nele adicione o código abaixo.

Quando invocamos a classe, ela tem acesso ao container de injeção de dependência (DI) da aplicação, a partir do qual irá recuperar os detalhes de configuração que armazenamos em “config/autoload/mail.global.php”.

Depois disso, ele instanciará um novo objeto “SendGrid\Mail\Mail” e definirá os detalhes de e responderá passando os respectivos detalhes de configuração para chamadas para os métodos “Mail”, “setFrom” e “setReplyTo”, respectivamente. Depois disso, ele retornará o objeto “Mail” instanciado.

Para usá-lo, porém, você precisa registrá-lo no contêiner DI. Para fazer isso, em “src/App/src/ConfigProvider”, adicione a seguinte entrada ao elemento “factories” no array retornado pelo método “getDependencies”.

Criar um manipulador para enviar e-mail

Em seguida, precisamos criar uma classe Handler para compor e enviar e-mails. Para isso, utilizaremos a ferramenta CLI do Mezzio , disponível via Composer, executando o comando abaixo.

A execução do comando acima faz quatro coisas para nós:

  1. Cria uma nova classe Handler, “src/App/Handler/EmailSenderHandler.php ”
  2. Cria uma classe de fábrica para instanciar a classe Handler, “src/App/Handler/EmailSenderHandlerFactory.php”
  3. Cria um arquivo de modelo (“src/App/templates/app/email-sender.html.<ext>”), que não precisaremos . O nome do arquivo “<ext>” é determinado pelo mecanismo de modelo que você escolheu durante o estágio “create-project”.
  4. Registra a nova classe Handler como um serviço no contêiner DI adicionando uma entrada a “config/autoload/mezzio-tooling-factories.global.php”

Refatorar o manipulador para enviar e-mails

Com o “EmailSenderHandler.php” criado, agora precisamos refatorá-lo para que ele possa enviar e-mails. Para fazer isso, primeiro refatoramos o construtor “EmailSenderHandler's”, substituindo o parâmetro “TemplateRendererInterface” por 3 novos parâmetros. Eles inicializarão 3 novas variáveis ​​de membro de classe:

  • Um objeto “\SendGrid\Mail\Mail”
  • Um objeto “\SendGrid”
  • Uma matriz contendo os detalhes de configuração necessários

Você pode ver o construtor revisado no exemplo abaixo, junto com as variáveis ​​de membro de classe relacionadas. Substitua a variável de membro de classe existente e o construtor por este código.

Nota: Em seguida, precisamos refatorar o método “handle”. Substitua o conteúdo existente do método “EmailSenderHandler” “handle” pelo código abaixo, então vamos ver o que ele faz.

Ele começa usando “$request->getParsedBody()” para recuperar quaisquer parâmetros fornecidos no corpo da solicitação, que retornará um array associativo, inicializando “$details”. Com os parâmetros disponíveis, chama o método “addTo” do objeto “SendGrid\Mail\Mail” para definir o destinatário do email, passando o endereço de email e o nome do destinatário nos 2 primeiros argumentos e um array de substituições no terceiro argumento.

As substituições permitem que você personalize as mensagens de e-mail para cada destinatário. Em emails de texto simples, qualquer string imediatamente cercada por hífens, por exemplo, “-first_name-” é uma substituição. Em emails HTML, ele usa a sintaxe Handlebars , que envolve as strings entre parênteses duplos, por exemplo, “{{ first_name }}.”

Em seguida, definimos o assunto da mensagem e adicionamos um texto simples e um corpo de mensagem HTML. Com isso, nosso e-mail está pronto para ser enviado. Então usamos o objeto “SendGrid”, “$this->mailer”, para enviá-lo, inicializando uma nova variável, “$response”, com a resposta da tentativa de enviar a mensagem. Por fim, retornamos um objeto JsonResponse , contendo o código de status e o corpo da resposta.

Nota: Refatorar o método __invoke de EmailSenderHandlerFactory

Agora que concluímos a refatoração de “EmailSenderHandler”, precisamos refatorar “EmailSenderHandlerFactory”. Isso instanciará “EmailSenderHandler” corretamente. Para fazer isso, substitua a definição existente de seu método “__invoke`” pelo código a seguir.

Isso recupera um objeto “\SendGrid\Mail\Mail” do contêiner DI, pré-inicializado com o remetente e responde aos detalhes do email, e inicializa um novo objeto chamado “$message”. Ele então instancia um novo objeto “SendGrid”, chamado “$mailer” para enviar a mensagem de correio. Por fim, recupera a configuração de correio da configuração do aplicativo. Em seguida, ele os usa para inicializar e retornar o objeto “EmailSenderHandler”.

Atualizar a tabela de roteamento

Com todas essas alterações, há uma última alteração a ser feita antes que possamos testar o código e enviar um e-mail. Temos que atualizar a tabela de roteamento para que a rota padrão use nossa nova classe Handler como manipulador da rota, em vez de “HomePageHandler”. Para fazer isso, substitua a definição da rota padrão em “config/routes.php” pelo exemplo a seguir.

Envie o primeiro e-mail

Agora é hora de enviar o primeiro e-mail. Para fazer isso, primeiro, inicie o aplicativo executando o comando abaixo no terminal.

Em seguida, usando cURL, faça uma solicitação GET para “ http://localhost:8080 ”, como no exemplo abaixo, substituindo os valores entre colchetes por detalhes relevantes para seu e-mail.

Você deverá ver a saída “{“status”:202,“message”:””}” no terminal e deverá receber um e-mail parecido com a imagem abaixo.

Nota: Use modelos de email transacional em vez de strings de modelo

Embora tenhamos sido capazes de enviar um e-mail com um corpo de texto simples e HTML, a forma como fizemos isso, no entanto, não é o ideal. Para cada e-mail que enviamos – e nosso aplicativo pode acabar enviando vários – precisaremos adicionar um texto simples e um corpo HTML para eles.

Mas armazenar as definições do corpo do email em código coloca a maior parte do esforço na equipe de desenvolvimento. No entanto, pelo menos na minha experiência, muitas vezes outras equipes, geralmente de marketing, criam e mantêm modelos de e-mail.

Então, por esse motivo, e porque isso aceleraria o desenvolvimento e compartilharia a carga entre várias equipes, vamos refatorar o aplicativo para usar modelos de e-mail transacionais . Você pode criá-los e mantê-los por meio da interface do usuário do Twilio SendGrid por membros da equipe que podem ter pouca ou nenhuma experiência técnica, em vez de em código.

Se você ainda não ouviu falar deles, o glossário do Twilio SendGrid os define da seguinte forma:

Os modelos de email transacional são layouts de email pré-codificados que profissionais de marketing, designers e desenvolvedores podem usar para criar campanhas de email transacional de maneira rápida e fácil. Os modelos de email transacional do Twilio SendGrid permitem que pessoas não técnicas e técnicas façam alterações em tempo real no email que seus destinatários recebem.

Para este artigo, precisamos apenas de um bastante básico. Para isso, siga os detalhes da documentação do Twilio SendGrid e crie um que tenha como conteúdo apenas um módulo de texto único. Então, para o corpo do texto, use o texto abaixo.

Observe que há 6 substituições no e-mail:

  • “first_name”: o primeiro nome do cliente
  • “last_name”: o sobrenome do cliente
  • “sender_name”: O nome da loja de e-commerce (The Little PHP Shop)
  • “sender_state”: o estado da loja de comércio eletrônico
  • “sender_country”: o país da loja de comércio eletrônico
  • “support_email”: o e-mail de suporte que os clientes podem usar para obter suporte pós-venda

Diante disso, precisamos disponibilizar essas informações para nosso aplicativo. O nome e sobrenome do cliente já temos. As 4 substituições restantes serão globais, então, como fizemos anteriormente, adicionaremos a configuração abaixo em “ config/autoload/mail.global.php ”, após o elemento “templates”.

Com o novo arquivo de configuração criado, no método “EmailSenderHandler” “handle”, substitua as 2 chamadas para “$this->mail->addContent()”, pelo código a seguir.

As 2 chamadas de método adicionam os detalhes do remetente e o endereço de e-mail de suporte como substituições globais. Essas substituições se aplicam ao corpo do email antes de qualquer outra substituição, mas são substituídas se houver substituições com a mesma chave para um destinatário de email.

Em seguida, você precisa recuperar o ID do modelo de email transacional. Você pode encontrá-lo clicando no nome do modelo na lista de modelos , como você pode ver na captura de tela abaixo.

Copie-o e armazene-o em “config/autoload/mail.global.php” em um novo elemento com a chave “template_id” e depois remova “plain” e “HTML”. Quando terminar, o elemento “mail/templates” do array retornado será parecido com o código abaixo, onde “<the template's id>” substitui o ID do seu template.

Com a configuração atualizada, agora precisamos adicionar uma chamada ao método “Mail” “setTemplateId” no método “EmailSenderHandler” “handle”, passando o ID do template que acabamos de adicionar em “config/autoload/mail.global. php.” Você pode ver um exemplo no código abaixo.

Vamos testar as mudanças

Como antes, usando cURL, faça uma solicitação GET para “ http://localhost:8080 ” para testar se as alterações funcionam conforme o esperado. Você deve ver a saída “{“status”:202,“message”:””}” para o terminal, como no exemplo anterior. Na sua caixa de entrada de e-mail, você deverá ver um e-mail adorável, com as substituições substituídas, como na captura de tela abaixo.

Anexar uma fatura em PDF

Agora que estamos usando modelos dinâmicos, vamos anexar a fatura em PDF sobre a qual falamos no início do artigo. Para economizar tempo e esforço de procurar ou criar uma, criei uma amostra de fatura em PDF que você pode usar para este artigo. Salve-o no diretório “dados” do aplicativo .

Observação: Para anexar uma fatura, precisamos usar o método “Mail” “addAttachment”, que você pode ver no próximo exemplo de código. O método recebe 5 argumentos, mas estamos fornecendo apenas os primeiros 4. Estes são:

  1. Um objeto “Anexo” ou uma string codificada em Base64 . Se o valor desse parâmetro não for codificado em base64, o método fará isso por nós.
  2. O tipo mime do anexo (agora conhecido como tipo de mídia ).
  3. O nome do arquivo do anexo . Este é o nome com o qual o arquivo será salvo, por padrão, a menos que o usuário o altere.
  4. A disposição do conteúdo do anexo . Se você não estiver familiarizado com disposição de conteúdo, disposição de conteúdo inline significa que o anexo deve ser exibido automaticamente quando a mensagem for exibida, e disposição de conteúdo do anexo significa que o anexo não é exibido automaticamente e requer alguma forma de ação do usuário para abra.

No exemplo de código abaixo, o método file_get_contents do PHP lê o conteúdo do arquivo em uma nova variável chamada “$invoice”. Em seguida, o PDF é anexado à mensagem chamando o método “addAttachment”.

Aqui nós:

  • Passe o conteúdo da fatura, que será codificada em Base64
  • Defina o tipo MIME como “application/pdf” pois estamos anexando um arquivo PDF
  • Defina o nome do arquivo da fatura para um nome fictício que um cliente possa esperar razoavelmente
  • Defina a disposição do conteúdo para "anexo"

Agora que terminamos essas alterações, vamos testar se elas funcionam. Execute a mesma solicitação cURL que executamos nas 2 vezes anteriores. Em seguida, na sua caixa de entrada de e-mail, você verá um e-mail adorável com o exemplo de fatura em PDF visível ao visualizar o e-mail.

É assim que se envia email com PHP usando Twilio SendGrid e Mezzio

Embora tenhamos apenas arranhado a superfície do que é possível enviar e-mails com Twilio SendGrid e Mezzio, agora você pode enviar um e-mail com texto simples e corpo HTML, bem como com um anexo. Você também aprendeu a usar modelos transacionais e substituições que podem ser definidas globalmente e por destinatário.

Recomendo fortemente que você dê uma olhada na documentação da biblioteca PHP para ver o que mais está disponível, como agendar envios de e-mail, anexar um arquivo do Amazon S3, adicionar cabeçalhos e adicionar seções e categorias.

Matthew Setter é um editor PHP na equipe Twilio Voices e – naturalmente – um desenvolvedor PHP. Ele também é o autor de Mezzio Essentials . Quando ele não está escrevendo código PHP, ele está editando ótimos artigos PHP aqui no Twilio. Ele pode ser contatado por:

  • E-mail: [email protected]
  • Site: http://matthewsetter.com
  • Twitter: @settermjd
  • GitHub: https://github.com/settermjd