Como receber e-mails com o Flask Framework para Python

Embora existam muitos tutoriais na Internet sobre como enviar e-mails, há muito pouco sobre como configurar um aplicativo para recebê-los e processá-los. Esta é uma tarefa que pode ser incrivelmente difícil se você estiver tentando configurar tudo sozinho, mas é tão fácil quanto receber uma solicitação da web ao usar o recurso Inbound Parse do Twilio SendGrid .

Neste breve tutorial, você aprenderá como fazer com que o Twilio SendGrid encaminhe seus e-mails diretamente para seu aplicativo da web, usando Python e a estrutura da web Flask.

Requisitos

Estes são os requisitos para concluir este tutorial:

• Python 3: Se seu sistema operacional não fornece um interpretador Python 3, você pode acessar python.org para baixar um instalador.
• Uma conta no Twilio SendGrid: Se você é novo no Twilio SendGrid, pode criar uma conta gratuita , que permite enviar 100 e-mails por dia para sempre.
• Um domínio no qual você receberá e-mails: Ao longo deste artigo, usarei yourdomainhere.com . Você precisará substituí-lo pelo seu próprio nome de domínio.
• ngrok : Usaremos este utilitário útil para conectar o aplicativo Flask executado localmente em seu computador a uma URL pública para a qual o SendGrid pode enviar solicitações. Isso é necessário para a versão de desenvolvimento do aplicativo porque seu computador provavelmente está atrás de um roteador ou firewall, portanto, não pode ser acessado diretamente na Internet. Se você não tiver o ngrok instalado, poderá baixar uma cópia para Windows, MacOS ou Linux .

Autenticação de domínio

Antes que o Twilio SendGrid possa aceitar e-mails em seu domínio, você precisa autenticá-lo , para que o Twilio SendGrid saiba que o domínio está sob seu controle.

Iniciar autenticação de domínio

Para autenticar seu domínio, faça login na sua conta do SendGrid e, na barra de navegação do lado esquerdo, abra “Configurações” para selecionar Autenticação do remetente .

Na página Sender Authentication , clique no botão “Get Started” na seção “Domain Authentication”.

Você será solicitado a selecionar seu provedor de DNS, que na maioria dos casos é a mesma empresa da qual você comprou seu domínio. Se o seu provedor de DNS não aparecer na lista, ou se você não souber quem ele é, basta selecionar “Não tenho certeza”.

Em seguida, você será questionado sobre como adicionar branding aos links que aparecem nos e-mails de saída. Este não é um tópico com o qual estamos preocupados no momento, portanto, selecione "Não". Você pode habilitar essa opção mais tarde se quiser usá-la.

Clique no botão “Next” para continuar para a próxima página.

Na página seguinte, você será solicitado a fornecer seu nome de domínio. Digitei yourdomainhere.com , e você precisará inserir o domínio que pretende usar. Você não precisa alterar nada na seção "Configurações avançadas".

Clique no botão “Avançar” para prosseguir.

A página agora exibirá 3 novos registros DNS que você precisa adicionar à configuração do seu domínio, cada um com um tipo, um nome de host e um valor. Para sua conveniência, o host e os valores podem ser copiados para a área de transferência. Abaixo você pode ver as configurações que me foram dadas. Os seus serão semelhantes, mas com seu próprio nome de domínio neles:

Adicionando entradas DNS ao seu domínio

A próxima etapa será diferente dependendo do seu provedor de DNS. Visite a página de configuração do seu domínio e descubra onde as configurações de DNS são editadas.

As capturas de tela abaixo são para o Google Domains . Você pode ver como adicionei o primeiro dos três registros DNS na imagem a seguir. Observe que os 3 registros com nomes @, ftp e www registros não estão relacionados a este tutorial e já foram definidos no meu domínio.

Tenha cuidado ao inserir o nome do registro DNS. Enquanto alguns provedores esperam um nome totalmente qualificado para seus registros DNS, conforme mostrado pelo SendGrid, outros esperam apenas a parte antes do nome de domínio. Por exemplo, o registro que o SendGrid mostrou como em3329.seudominioaqui.com teve que ser inserido como em3329 no Google Domains. Verifique seus outros registros DNS e seja consistente na forma como você insere esses novos registros.

Aqui está como os 3 novos registros DNS ficaram depois que eu os inseri:

Verificação de domínio

Agora volte para a página SendGrid Sender Authentication , onde seu domínio aparecerá como pendente. Clique nele para prosseguir com o processo de autenticação.

Na próxima tela, você verá os 3 registros DNS. Clique no botão "Verificar" no canto superior direito da página para que o SendGrid extraia seus registros DNS e confirme que você adicionou as entradas solicitadas.

Se o SendGrid puder verificar seu domínio, você receberá um "Funcionou!" página:

Se, por outro lado, o SendGrid não puder verificar suas entradas DNS, você precisará tentar novamente mais tarde. Toda vez que as alterações de DNS são feitas, leva algum tempo para que as alterações se propaguem pelos servidores DNS. Uma falha logo após editar suas entradas DNS significa apenas que você precisa esperar um pouco mais antes de clicar no botão “Verificar” novamente. Observe que pode levar até 48 horas para que o DNS seja totalmente propagado, embora geralmente leve muito menos tempo.

Depois de obter o "funcionou!" página, você está no caminho certo para obter e-mails postados em seu aplicativo da web Flask.

Um aplicativo de e-mail Flask

Agora estamos prontos para escrever um aplicativo Web Flask simples onde o SendGrid pode encaminhar nossos e-mails.

Criar um ambiente virtual Python

Seguindo as melhores práticas do Python, vamos criar um diretório separado para nosso projeto e dentro dele vamos criar um ambiente virtual . Em seguida, vamos instalar o framework Flask nele.

Se você estiver usando um sistema Unix ou Mac OS, abra um terminal e digite os seguintes comandos para realizar as tarefas descritas acima:

Se você estiver seguindo o tutorial no Windows, digite os seguintes comandos em uma janela de prompt de comando:

Uma rota de e-mail de entrada

Vamos agora escrever um aplicativo Flask que receberá e-mails recebidos. O código para o aplicativo completo é mostrado abaixo. Coloque este código em um arquivo chamado app.py .

O aplicativo possui apenas uma rota da web conectada à URL /email . Teremos que o SendGrid invoque essa rota para passar os emails recebidos para nós. A solicitação que eles enviarem terá todos os detalhes relacionados ao e-mail enviado como uma postagem de formulário HTTP padrão. Isso significa que a partir do Flask podemos acessar facilmente todos esses detalhes do dicionário `request.form`.

As seguintes variáveis ​​de formulário são de particular interesse:

• `request.form['from']`: o remetente do email
• `request.form['to']`: o(s) destinatário(s) do email
• `request.form['subject']`: o assunto do email
• `request.form['text']` o corpo do email em formato de texto simples
• `request.form['html']` o corpo do email em formato HTML

Observe que esses não são os únicos campos enviados pelo SendGrid. Revise a lista completa de parâmetros de email na documentação do SendGrid.

Como o processamento de e-mails depende muito de cada aplicativo, para o exemplo do aplicativo Flask, tudo o que estamos fazendo é imprimir os campos de e-mail no console.

Depois de salvar app.py , você pode iniciar o aplicativo Flask da seguinte maneira:

O aplicativo agora está em execução e escutando as solicitações recebidas, mas só pode ser acessado a partir do seu próprio computador. Deixe o aplicativo em execução na janela do terminal por enquanto. Na próxima seção vamos expô-lo à Internet.

O webhook de análise de entrada do SendGrid

O último deste tutorial é configurar o SendGrid para encaminhar e-mails recebidos em seu domínio para o aplicativo Flask.

Iniciando ngrok

A ferramenta ngrok cria um URL disponível publicamente e o mapeia para um aplicativo executado localmente. Essa é uma técnica comum usada para expor serviços na Internet para desenvolvimento e teste. Quando seu aplicativo Flask estiver concluído, você o implantará para produção em um servidor adequado e isso não será mais necessário.

Se você ainda não o fez, instale o ngrok em seu sistema. Deixe o aplicativo Flask em execução e abra uma segunda janela de terminal para iniciar o ngrok da seguinte forma:

Isso está dizendo ao ngrok para criar um “túnel” da Internet pública para a porta 5000 em nossa máquina local, onde o aplicativo Flask está aguardando solicitações da web. A saída do ngrok será a seguinte:

Observe as linhas começando com “Forwarding” na tela ngrok. Eles mostram uma URL pública gerada aleatoriamente que o ngrok usa para redirecionar solicitações para nosso serviço. Vamos usar a URL https:// porque ela usa criptografia.

Registrando a URL do webhook com o SendGrid

Volte para o painel do SendGrid e, em Configurações, selecione Análise de entrada e clique em “Adicionar host e URL”.

Na próxima página, digite o subdomínio no qual você receberá e-mails. Pode ser qualquer subdomínio que ainda não esteja em uso em seu domínio ou, se você preferir receber e-mails diretamente em seu domínio de nível superior, pode deixá-lo vazio. Na imagem abaixo, usei o subdomain parse , o que significa que os emails que são aceitos pelo SendGrid terão o formato < Anything>@parse.yourdomainhere.com . Deixar o campo de subdomínio vazio permitirá que o SendGrid aceite emails para <qualquer coisa>@seudominioaqui.com , o que em alguns casos pode ser preferível.

Em seguida, você deve selecionar seu nome de domínio . Esta é uma lista suspensa que mostra todos os domínios que você verificou com o SendGrid. Se você estiver fazendo isso pela primeira vez, verá apenas o domínio verificado anteriormente.

O campo a seguir é para o URL de destino do seu webhook. Este é o URL gerado pelo ngrok anexado com o URL do Flask /email . No meu caso, foi https://bbf1b72b.ngrok.io/email . Você terá uma URL semelhante, mas a primeira parte do nome do host ngrok será diferente.

Clique em “Adicionar” para configurar seu webhook.

Agora você verá uma entrada para seu webhook na página principal do Inbound Parse:

Observação: as URLs do ngrok mudam toda vez que o ngrok é interrompido e reiniciado, portanto, durante o desenvolvimento, você precisará editar seu webhook para atualizar o URL sempre que reiniciar o ngrok. Ao implantar seu webhook para uso em produção, você o hospedará diretamente em uma URL pública, portanto, o ngrok não será usado.

Registrando o subdomínio de análise

O subdomínio que você selecionou para receber e-mails na seção anterior precisa ser definido na configuração de DNS do seu domínio com um registro `MX`. O valor para este registro é o mesmo para todos os clientes do SendGrid: `mx.sendgrid.net.` (observe o ponto final após “net”).

Na minha configuração de DNS do Google Domains, defini meu subdomínio de análise da seguinte forma:

Lembre-se de que, dependendo do provedor de domínio que você usa, pode ser necessário inserir o nome de host completo para esse registro DNS, portanto, nesse caso, seria parse.yourdomainhere.com .

Se você decidiu não definir um subdomínio na seção anterior, seu nome de host será yourdomainhere.com , que para alguns provedores de DNS deve ser fornecido como " @".

Lembre-se de que essa alteração de DNS também precisará ser propagada, portanto, talvez você não consiga receber e-mails imediatamente.

Enviando um e-mail de teste

Enquanto o aplicativo Flask e o ngrok estiverem em execução, abra seu cliente de e-mail e envie um e-mail de teste. No campo “Para:” você pode inserir qualquer nome de usuário que desejar, pois o SendGrid captura todos os nomes de usuário. O que vem depois do @ precisa ser seu domínio completo de recebimento de e-mail.

No exemplo abaixo enviei um email para [email protected] :

Aguarde um minuto ou dois para que o SendGrid receba o email e o encaminhe para a URL do webhook ngrok, que por sua vez o passará para o ponto de extremidade /email do Flask. Como você viu acima, o endpoint simples que escrevi no aplicativo Flask imprime os dados de e-mail recebidos no console:

Então é isso, agora estamos recebendo e-mails como solicitações da web em nosso aplicativo Flask!

Implantação de produção

Nesta seção, quero destacar algumas diferenças importantes entre os webhooks implantados durante o desenvolvimento e aqueles destinados ao uso em produção.

Implantações sem ngrok

Como mencionado acima, o ngrok não é uma ferramenta de produção e nunca deve ser usado em uma implantação de produção. Em vez disso, você implantará seu aplicativo Flask em um servidor conectado diretamente à Internet. Existem várias opções de implantação discutidas na documentação do Flask.

Segurança do webhook

Considere que seu terminal de recebimento de e-mail está disponível publicamente na Internet, para que qualquer pessoa que conheça a URL possa enviar uma solicitação a ele, potencialmente expondo seu aplicativo a invocações espúrias enviadas por usuários mal-intencionados fingindo ser solicitações do SendGrid.

Uma boa medida para evitar esse tipo de ataque é implementar a autenticação básica em seu endpoint Flask. A extensão Flask-HTTPAuth pode ser útil na implementação desse tipo de segurança.

Se você adicionar autenticação ao seu endpoint, precisará incluir o nome de usuário e a senha no URL do webhook fornecido ao SendGrid. O webhook que usei acima teria que ser fornecido como https://username:[email protected]/email.

Conclusão

Embora haja muitas etapas envolvidas na configuração de tudo para receber e-mails, essa é uma das maneiras mais simples de conseguir isso. Para obter mais informações sobre o Inbound Parse, confira nossa página de documentos.

Mal podemos esperar para ver o que você constrói com o Inbound Parse!