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.

  1. 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.

  2. 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 vai retornar um iterador que produz corpos HTML primeiro e depois 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.

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

  3. 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.