Esta página foi traduzida pela API Cloud Translation.

Como receber e-mails com a API Mail

Este guia descreve como usar a API Mail para receber e-mails.

As mensagens de e-mail enviadas para seu app são implementadas como solicitações HTTP contendo dados MIME. Para processar as mensagens de e-mail recebidas, associe os endereços de e-mail aos gerenciadores de script na configuração do seu aplicativo e inclua os gerenciadores no código do aplicativo.

O e-mail recebido gera solicitações HTTP, que são passadas aos scripts apropriados. Os scripts que gerenciam os e-mails recebidos precisam residir em seu serviço padrão.

Para mais informações sobre o serviço de e-mail, consulte a Visão geral da API Mail.

Antes de começar

Você precisa registrar seus remetentes de e-mails como remetentes autorizados. Para mais informações, consulte quem pode enviar e-mails.

Como configurar o aplicativo para receber e-mails

Quando você cria um novo app, o recebimento de e-mail está desativado por padrão. Para ativar o recebimento de e-mail, é preciso modificar o arquivo app.yaml em seu serviço padrão.

Adicione uma seção inbound_services que ative o serviço de recebimento de e-mail. Exemplo:
```
inbound_services:
- mail
```
Se você não ativar o recebimento de e-mail incluindo essa seção no seu arquivo de configuração, o recurso será desativado e as mensagens de e-mail enviadas para o aplicativo serão ignoradas.
Adicione mapeamentos que associem os endereços de e-mail mapeados por URL aos gerenciadores de script.

Para o serviço padrão, o endereço de e-mail de recebimento tem este formato:
```
[STRING]@[Google Cloud project ID].appspotmail.com
```
Para serviços não padrão, o endereço de e-mail tem este formato:
```
[STRING]@[servicename]-dot-[Google Cloud project ID].appspotmail.com
```
As mensagens de e-mail são enviadas para seu app como solicitações POST HTTP usando o URL a seguir, em que [ADDRESS] é um endereço de e-mail completo, incluindo o nome do domínio:
```
/_ah/mail/[ADDRESS]
```
Para manipular os e-mails recebidos em seu app, mapeie os URLs de e-mail para os gerenciadores no arquivo app.yaml:
```
- url: /_ah/mail/.+
  script: handle_incoming_email.app
  login: admin
```
No exemplo acima, /_ah/mail/.+ corresponde a todos os e-mails endereçados ao app. Se preferir, configure vários gerenciadores para endereços de e-mail diferentes, como no exemplo a seguir:
```
- url: /_ah/mail/owner@.*your_app_id\.appspotmail\.com
  script: handle_owner.app
  login: admin
- url: /_ah/mail/support@.*your_app_id\.appspotmail\.com
  script: handle_support.app
  login: admin
- url: /_ah/mail/.+
  script: handle_catchall.app
  login: admin
```
URLs de mensagens de e-mail recebidas são comparados a essa lista, do primeiro ao último, e se o URL de uma mensagem de e-mail corresponder a mais de um padrão, o primeiro gerenciador correspondente será o executado. Isso possibilita incluir um gerenciador "pega-tudo" como o último mapeamento. Os gerenciadores são executados no módulo padrão (ou versão do aplicativo).

Como manipular os e-mails recebidos

Ao usar frameworks da Web em Python, o construtor InboundEmailMessage recebe os bytes do corpo da solicitação HTTP. Há várias maneiras de criar o objeto InboundEmailMessage no Python. No Flask, request.get_data() fornece os bytes da solicitação. O objeto InboundEmailMessage contém a mensagem de e-mail. O método bodies() retorna os corpos dentro da mensagem. Se você chamar bodies() sem argumentos, ele retornará um iterador que produz corpos HTML primeiro e, em seguida, corpos de texto simples. Se quiser apenas HTML ou apenas texto simples, passe um argumento para bodies():

@app.route("/_ah/mail/<path>", methods=["POST"])
def receive_mail(path):
    message = mail.InboundEmailMessage(request.get_data())

    # Do something with the message
    print(
        f"Received greeting for {escape(message.to)} at {escape(message.date)} from {escape(message.sender)}"
    )
    for content_type, payload in message.bodies("text/plain"):
        print(f"Text/plain body: {payload.decode()}")
        break

    return "OK", 200

O objeto InboundEmailMessage inclui atributos para acessar outros campos de mensagens:

subject contém o assunto da mensagem.
sender é o endereço do remetente, como "Nobody <nobody@example.com>".
to é uma lista separada por vírgulas dos principais destinatários da mensagem, por exemplo, "Joe <joe@example.com>, Bill <bill@example.com>".
cc contém uma lista separada por vírgulas dos destinatários cc, por exemplo, "Joe <joe@example.com>, Bill <bill@example.com>".
date retorna a data da mensagem.
attachments é uma lista de objetos Attachment, possivelmente vazia.
original é a mensagem completa, incluindo dados não expostos por outros campos, como cabeçalhos de e-mail, na forma de email.message.Message do Python (em inglês).

Como simular mensagens recebidas no servidor de desenvolvimento local

Depois de definir o aplicativo para processar o recebimento de e-mail, é possível usar o console do servidor de desenvolvimento para simular mensagens de e-mail recebidas.

Acesse o servidor de desenvolvimento como administrador. Para isso, navegue até http://localhost:8080/console e clique em Fazer login como administrador.
No servidor de desenvolvimento, clique em E-mail de entrada na navegação.
Preencha o formulário exibido e clique em Enviar e-mail.

Para executar o servidor de desenvolvimento, consulte o servidor de desenvolvimento local.

Saiba mais sobre as considerações de migração para a API Mail no guia Gerenciadores de e-mail.