API Mail per Python

Questa pagina descrive come utilizzare la Mail API, uno dei servizi in bundle legacy, con il runtime Python per l'ambiente standard. La tua app può accedere ai servizi in bundle tramite l'SDK dei servizi App Engine per Python.

Panoramica

In Python, la funzionalità di gestione della posta è inclusa nel google.appengine.api.mail modulo. Questo è diverso da Python 2, dove il modulo mail_handlers è stato fornito da webapp. La Mail API per Python può essere utilizzata per ricevere email e notifiche di mancato recapito.

Utilizzo della Mail API

La tua app riceve la posta quando un'email viene inviata come corpo della richiesta in una richiesta HTTP POST. Affinché l'app gestisca le email in entrata, deve far corrispondere l'URL al percorso /_ah/mail/[ADDRESS]. La parte [ADDRESS] del percorso è in genere un indirizzo email con il suffisso @<Cloud-Project-ID>.appspotmail.com. Le email inviate all'app in questo formato verranno indirizzate alla funzione.

Python non richiede che l'app specifichi uno script del gestore nel file app.yaml, quindi puoi rimuovere tutte le sezioni handler in app.yaml.

Il file app.yaml deve mantenere le seguenti righe:

inbound_services:
- mail
- mail_bounce

Invio di posta

Non devi apportare modifiche alla configurazione della tua app durante l'upgrade a Python. Il comportamento, le funzionalità e le istruzioni di configurazione per l'invio di posta rimangono invariati. Per maggiori dettagli, consulta il riferimento dell'API Mail per Python.

Ricezione di posta

Per ricevere la posta, devi importare il modulo google.appengine.api.mail e utilizzare la classe InboundEmailMessage per rappresentare un'email. Questa classe deve essere creata un'istanza per recuperare il contenuto dell'email dalla richiesta HTTP in entrata.

In precedenza, in Python 2, le app potevano accedere alla classe InboundEmailMessage sostituendo il metodo receive() nel gestore webapp InboundEmailHandler. Non è necessario in Python; al contrario, l'app deve creare un'istanza di un nuovo oggetto.

Framework web

Quando si utilizzano i framework web Python, il costruttore InboundEmailMessage accetta i byte del corpo della richiesta HTTP. Esistono diversi modi per creare l'oggetto InboundEmailMessage in Python. Di seguito sono riportati alcuni esempi per le app Flask e Djago:

Python 3 (Flask)

In Flask, request.get_data() fornisce i byte della richiesta.

@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

Python 3 (Django)

In Django, request.body fornisce i byte del corpo della richiesta HTTP.

def receive_mail(request):
    message = mail.InboundEmailMessage(request.body)

    print(f"Received greeting for {message.to} at {message.date} from {message.sender}")
    for _, payload in message.bodies("text/plain"):
        print(f"Text/plain body: {payload.decode()}")
        break

    return HttpResponse("OK")

Per visualizzare gli esempi di codice completi di questa guida, consulta GitHub.

Altri framework conformi a WSGI

Per altri framework conformi a WSGI, ti consigliamo di utilizzare lo stesso metodo degli esempi di Flask e Django per creare InboundEmailMessage. Questo metodo funziona quando i byte del corpo della richiesta HTTP sono disponibili direttamente.

App WSGI senza framework web

Se la tua app è un'app WSGI che non utilizza un framework web, è possibile che i byte del corpo della richiesta HTTP non siano disponibili direttamente. Se i byte del corpo della richiesta HTTP sono disponibili direttamente, ti consigliamo di utilizzare un framework web Python.

In Python, per InboundEmailMessage è definito un metodo di fabbrica denominato from_environ. Questo metodo è un metodo di classe che accetta il dizionario environWSGI come input e può essere utilizzato per qualsiasi applicazione WSGI.

Nell'esempio seguente, nota come environ viene utilizzato come input per ottenere mail_message:

Python 3 (app WSGI)

def HelloReceiver(environ, start_response):
    if environ["REQUEST_METHOD"] != "POST":
        return ("", http.HTTPStatus.METHOD_NOT_ALLOWED, [("Allow", "POST")])

    message = mail.InboundEmailMessage.from_environ(environ)

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

    response = http.HTTPStatus.OK
    start_response(f"{response.value} {response.phrase}", [])
    return ["success".encode("utf-8")]

Ricezione di notifiche di mancato recapito

Una notifica di mancato recapito è un messaggio automatico di un sistema email che indica un problema con la consegna dei messaggi della tua app. Per elaborare le notifiche di mancato recapito, la tua app deve far corrispondere i percorsi URL in entrata al percorso /_ah/bounce.

Come InboundEmailMessage, la classe BounceNotification per Python 2 era accessibile sostituendo il metodo receive() nel gestore webapp BounceNotificationHandler.

In Python, l'app deve creare un'istanza dell'oggetto BounceNotification, che può essere creato in diversi modi a seconda del framework web Python utilizzato.

Framework web

L'oggetto BounceNotification viene inizializzato con i valori recuperati chiamando post_vars.get(key).

Quando si utilizza un framework web Python, come Flask o Django, il costruttore BounceNotification accetta un dizionario denominato post_vars, che contiene la richiesta POST dei dati del modulo. Per recuperare i dati, è necessario definire il metodo get() sull'oggetto di input. La key è un elenco di valori di input che possono essere letti e recuperati da BounceNotification e può essere uno dei seguenti:

original-to, original-cc, original-bcc, original-subject, original-text, notification-from, notification-to, notification-cc, notification-bcc, notification-subject, notification-text, raw-message

Nella maggior parte dei framework web, questi dati sono disponibili come dizionario multiplo nell'oggetto della richiesta. La maggior parte di questi tipi può essere convertita in un dizionario con chiavi di stringhe.

Per tutte le chiavi tranne raw-message, il valore può essere qualsiasi. In genere, il valore è un singolo valore, ad esempio una stringa, o un elenco di valori, ad esempio {'to': ['bob@example.com', 'alice@example.com']}. Il valore predefinito per tutti i campi è una stringa vuota. Questi valori verranno inseriti nelle proprietà original e notification.

Per la chiave raw-message, il valore deve essere un input valido per il costruttore di EmailMessage. Può essere un singolo valore o un elenco di valori singoli. La chiave raw-message viene utilizzata per inizializzare la proprietà original_raw_message dell'oggetto.

Python 2 (webapp2)

class LogBounceHandler(BounceNotificationHandler):
    def receive(self, bounce_message):
        logging.info('Received bounce post ... [%s]', self.request)
        logging.info('Bounce original: %s', bounce_message.original)
        logging.info('Bounce notification: %s', bounce_message.notification)

Python 3 (Flask)

In Flask, request.form di tipo werkzeug.datastructures.MultiDict fornisce le variabili POST. Tuttavia, il metodo get() per questo tipo restituisce solo un valore, anche se sono presenti più valori per la chiave.

Per ottenere tutti i valori corrispondenti a una chiave, l'app deve chiamare dict(request.form.lists()), che genera un dizionario in cui ogni valore è un elenco.

@app.route("/_ah/bounce", methods=["POST"])
def receive_bounce():
    bounce_message = mail.BounceNotification(dict(request.form.lists()))

    # Do something with the message
    print("Bounce original: ", bounce_message.original)
    print("Bounce notification: ", bounce_message.notification)

    return "OK", 200

Python 3 (Django)

In Django, request.POST di tipo django.http.QueryDict fornisce le variabili POST. Tuttavia, il metodo get() per questo tipo restituisce solo un valore, anche se sono presenti più valori per la chiave.

Per ottenere tutti i valori corrispondenti a una chiave, l'app deve chiamare dict(request.POST.lists()), che genera un dizionario in cui ogni valore è un elenco.

def receive_bounce(request):
    bounce_message = mail.BounceNotification(dict(request.POST.lists()))

    # Do something with the message
    print(f"Bounce original: {bounce_message.original}")
    print(f"Bounce notification: {bounce_message.notification}")

    return HttpResponse("OK")

App WSGI senza framework web

Se la tua app è un'app WSGI che non utilizza un framework web, è possibile che le variabili del modulo della richiesta HTTP POST non siano disponibili direttamente in un dizionario.

In Python, per BounceNotification è definito un metodo di fabbrica denominato from_environ. Questo metodo è un metodo di classe che accetta il dizionario WSGI environ come input e può essere utilizzato per qualsiasi applicazione WSGI.

Nell'esempio seguente, nota come environ viene utilizzato come input per ottenere bounce_message:

Python 3

def BounceReceiver(environ, start_response):
    if environ["REQUEST_METHOD"] != "POST":
        return ("", http.HTTPStatus.METHOD_NOT_ALLOWED, [("Allow", "POST")])

    bounce_message = mail.BounceNotification.from_environ(environ)

    # Do something with the message
    print("Bounce original: ", bounce_message.original)
    print("Bounce notification: ", bounce_message.notification)

    # Return suitable response
    response = http.HTTPStatus.OK
    start_response(f"{response.value} {response.phrase}", [])
    return ["success".encode("utf-8")]

Esempi di codice

Per visualizzare gli esempi di codice completi di questa guida, consulta GitHub.