Como enviar e-mails com SendGrid

Neste tutorial, mostramos como usar o SendGrid para enviar e-mails de um aplicativo em execução em uma instância de máquina virtual (VM, na sigla em inglês) do Compute Engine.

Objetivos

  • Usar o SendGrid com o Postfix em uma instância do Compute Engine.
  • Usar o SendGrid em código Java executado em uma instância do Compute Engine.
  • Usar o SendGrid em código Node.js executado em uma instância do Compute Engine.
  • Usar o SendGrid com um servidor de transporte de borda do Microsoft Exchange em uma instância do Compute Engine.

Para mais informações sobre como configurar o SendGrid, consulte a documentação do desenvolvedor do SendGrid (em inglês).

Custos

Neste tutorial, usamos componentes faturáveis do Google Cloud, incluindo o Compute Engine.

Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Antes de começar

  1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
  2. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  3. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

  4. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  5. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

  6. No Console do Cloud, acesse a página Instâncias de VM.

    Acessar instâncias de VM

  7. Clique em Criar instância.
  8. Defina Nome como sendgrid-tutorial.
  9. Na seção Disco de inicialização, clique em Alterar para começar a configurar o disco de inicialização.
  10. Na guia Public images, escolha a Debian or CentOS image version.

  11. Clique em Select.
  12. Clique em Criar para criar a instância.
  13. Use o Google Cloud Marketplace para se inscrever no serviço de e-mail do SendGrid. Anote as credenciais da conta SMTP do SendGrid, que incluem nome de usuário, senha e nome do host. O nome de usuário e a senha SMTP são iguais aos da inscrição no serviço. O nome do host do SendGrid é smtp.sendgrid.net.
  14. Crie uma chave de API:
    1. Faça login no SendGrid e acesse Configurações > Chaves de API.
    2. Crie uma chave de API.
    3. Selecione as permissões para a chave. Para enviar e-mails, a chave precisa, no mínimo, de permissões de envio de e-mail.
    4. Clique em Salvar para criar a chave.
    5. O SendGrid gera uma nova chave. Esta é a única cópia da chave, portanto, faça uma cópia dela e salve-a para uso futuro.

Como enviar e-mails da instância com o Postfix

Conclua as etapas a seguir para se conectar à instância do sendgrid-tutorial e executar o SendGrid com o Postfix.

Conectar-se à instância "tutorial-sendgrid" usando o SSH

  1. No Console do Cloud, acesse a página Instâncias de VM.

    Acessar instâncias de VM

  2. Na lista de instâncias de máquina virtual, clique em SSH na linha da instância à qual você quer se conectar.

Como configurar o SendGrid como um redirecionamento SMTP com o Postfix

Execute os comandos a seguir no terminal SSH para usar o SendGrid como um redirecionamento SMTP com o Postfix.

  1. Torne-se um superusuário:

    sudo su -
    
  2. Defina um umask seguro:

    umask 077
    
  3. Instale o agente de transporte de e-mail do Postfix.

    Debian

    apt update && apt -y install postfix libsasl2-modules

    CentOS

    yum install postfix cyrus-sasl-plain cyrus-sasl-md5 -y

    Se solicitado, selecione a configuração Somente local e aceite o nome de domínio padrão.

  4. Modifique as opções de configuração do Postfix. Abra /etc/postfix/main.cf para edição. Por exemplo, para usar o editor de texto nano, digite o comando a seguir:

    nano /etc/postfix/main.cf
    
  5. Atualize o arquivo:

    1. Marque as seguintes linhas como comentários:

      # default_transport = error
      # relay_transport = error
      
    2. Adicione estas linhas ao final do arquivo:

      relayhost = [smtp.sendgrid.net]:2525
      smtp_tls_security_level = encrypt
      smtp_sasl_auth_enable = yes
      smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
      header_size_limit = 4096000
      smtp_sasl_security_options = noanonymous
      

      As linhas acima aplicam o suporte SSL/TLS e configuram a autenticação SMTP para essas solicitações. Na configuração do Postfix, a autenticação é processada por um módulo de camada simples de autenticação e segurança (SASL, na sigla em inglês).

  6. Salve e feche o arquivo.

  7. Crie o mapa de senhas SASL usando a chave de API gerada na seção Antes de começar. Substitua your-api-key pela chave de API que foi gerada.

    echo [smtp.sendgrid.net]:2525 apikey:your-api-key >> /etc/postfix/sasl_passwd
  8. Use o utilitário postmap para gerar um arquivo .db:

    postmap /etc/postfix/sasl_passwd
    
  9. Verifique se há um arquivo .db:

    ls -l /etc/postfix/sasl_passwd*
    
    -rw------- 1 root root    ...  /etc/postfix/sasl_passwd
    -rw------- 1 root root    ...  /etc/postfix/sasl_passwd.db
    
  10. Remova o arquivo com suas credenciais, porque ele não é mais necessário:

    rm /etc/postfix/sasl_passwd
    
  11. Defina as permissões no arquivo .db e verifique se o outro arquivo foi removido:

    chmod 600 /etc/postfix/sasl_passwd.db
    ls -la /etc/postfix/sasl_passwd.db
    
    -rw------- 1 root root    ...  /etc/postfix/sasl_passwd.db
    
  12. Recarregue sua configuração com os parâmetros modificados:

    Debian

    /etc/init.d/postfix restart
    

    CentOS

    postfix reload
    

  13. Instale o pacote mailutils ou mailx:

    Debian

    apt -y install mailutils

    CentOS

    yum install mailx -y
    

  14. Envie um e-mail de teste:

    echo 'message' | mail -s subject email@example.com

    Substitua:

    • message: o corpo do e-mail.
    • subject: o assunto do e-mail.
    • email@example.com: o endereço de e-mail a que você quer enviar e-mails.

    Nos registros do sistema, procure uma linha de status que contenha status e o código de resposta bem-sucedida do servidor (250):

    Debian

    tail -n 5 /var/log/syslog
    

    CentOS

    tail -n 5 /var/log/maillog
    

Enviar e-mails com Java na instância

Conectar-se à instância "tutorial-sendgrid" usando o SSH

  1. No Console do Cloud, acesse a página Instâncias de VM.

    Acessar instâncias de VM

  2. Na lista de instâncias de máquina virtual, clique em SSH na linha da instância à qual você quer se conectar.

Criar e enviar uma mensagem de e-mail

Nas instruções a seguir, a biblioteca de cliente Java do SendGrid é usada para criar e enviar uma mensagem de e-mail pelo SendGrid. Veja o exemplo completo no GitHub (em inglês).

No terminal do SSH:

  1. Conecte-se como um superusuário e configure um umask seguro:

    sudo su -
    umask 077
    
  2. Instale o Java e o Maven:

    apt -y update && apt -y install git-core openjdk-11-jdk maven
    
  3. Clone o repositório do GitHub:

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
    
  4. Acesse o código-fonte principal do exemplo:

    cd /root/java-docs-samples/compute/sendgrid/src/main/java/com/example/compute/sendgrid
    
  5. Abra SendEmailServelet.java para edição.

    • Substitua your-sendgrid-api-key pela chave de API (em inglês) que você copiou para sua conta do SendGrid.

    • Substitua your-sendgrid-from-email pelo endereço de e-mail que você quer usar para enviar e-mails.

    • Substitua destination-email pelo endereço de e-mail a que você quer enviar e-mails.

  6. Acesse o diretório raiz do código de amostra:

    cd /root/java-docs-samples/compute/sendgrid
    
  7. Crie o pacote da classe Java:

    mvn clean package
    
  8. Acesse o novo diretório target:

    cd target
    
  9. Defina as permissões para executar o arquivo jar:

    chmod +x compute-sendgrid-1.0-SNAPSHOT-jar-with-dependencies.jar
    
  10. Execute o seletor de versão alternativa de Java:

    update-alternatives --config java
    

    Selecione a opção java-11-openjdk-amd64.

  11. Execute o arquivo Java:

    java -jar compute-sendgrid-1.0-SNAPSHOT-jar-with-dependencies.jar
    

Como enviar e-mails com o Node.js na instância

Para executar esta amostra, é necessário ter a versão 7.6 ou mais recente de Node.js instalado na instância de VM.

Conectar-se à instância "tutorial-sendgrid" usando o SSH

  1. No Console do Cloud, acesse a página Instâncias de VM.

    Acessar instâncias de VM

  2. Na lista de instâncias de máquina virtual, clique em SSH na linha da instância à qual você quer se conectar.

Criar e enviar uma mensagem de e-mail

No terminal do SSH:

  1. Conecte-se como um superusuário e configure um umask seguro:

    sudo su -
    umask 077
    
  2. Atualize os repositórios de pacotes:

    Debian

    apt update
    

    CentOS

    yum update -y
    

  3. Instale as dependências do Node.js:

    Debian

    apt -y install git-core curl build-essential openssl libssl-dev
    

    CentOS

    yum install git-core curl openssl openssl-devel -y
    yum groupinstall "Development Tools" -y
    

  4. Instale o Node.js. Por padrão, npm também é instalado:

    Debian

    curl -sL https://deb.nodesource.com/setup_14.x | sudo bash -
    sudo apt -y install nodejs
    

    CentOS

    curl --silent --location https://rpm.nodesource.com/setup_14.x | bash -
    

    Depois instale o Node.js:

    yum -y install nodejs
    

  5. Instale o cliente Node.js do SendGrid:

    npm install sendgrid
    
  6. Clone o repositório de amostra:

    git clone https://github.com/googleapis/nodejs-compute.git
    
  7. Acesse o diretório que contém a amostra do SendGrid:

    cd nodejs-compute/samples
    
  8. Copie o arquivo sendgrid.js:

    cp sendgrid.js sendmail.js
    
  9. Abra sendmail.js para edição.

    • Substitua your-sendgrid-api-key pela chave de API (em inglês) que você copiou para sua conta do SendGrid.

    • Substitua from-email@example.com pelo endereço de e-mail que você quer usar para enviar e-mails.

    • Substitua to-email@example.com pelo endereço de e-mail a que você quer enviar e-mails.

    // This sample is based off of:
    // https://github.com/sendgrid/sendgrid-nodejs/tree/master/packages/mail
    const sendgrid = require('@sendgrid/mail');
    sendgrid.setApiKey(process.env.SENDGRID_API_KEY || '<your-sendgrid-api-key>');
    
    async function sendgridExample() {
      await sendgrid.send({
        to: 'to_email@example.com',
        from: 'from_email@example.com',
        subject: 'Sendgrid test email from Node.js on Google Cloud Platform',
        text: 'Well hello! This is a Sendgrid test email from Node.js on Google Cloud Platform.',
      });
    }
    sendgridExample();

  10. Execute o programa para enviar uma mensagem de e-mail pelo SendGrid:

    node sendmail.js
    

Como enviar e-mails de um servidor de transporte de borda do Exchange

É possível fazer com que o Microsoft Exchange envie e-mails de saída com o SendGrid. Para isso, basta configurar um conector de envio de saída. Para mais detalhes, acesse Como implantar o Microsoft Exchange Server 2016 no Compute Engine.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Exclua o projeto

O jeito mais fácil de evitar cobranças é excluir o projeto que você criou para o tutorial.

Para excluir o projeto, faça o seguinte:

  1. No Console do Cloud, acesse a página Gerenciar recursos:

    Acessar "Gerenciar recursos"

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
  3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Excluir a instância do Compute Engine

Para excluir uma instância do Compute Engine, faça o seguinte:

  1. No Console do Cloud, acesse a página Instâncias de VM.

    Acessar instâncias de VM

  2. Marque a caixa de seleção de sua instância sendgrid-tutorial.
  3. Para excluir a instância, clique em Mais ações, clique em Excluir e siga as instruções.

A seguir

Explore arquiteturas de referência, diagramas, tutoriais e práticas recomendadas sobre o Google Cloud. Confira o Centro de arquitetura do Cloud.