Receiving bounce notification

In order to receive email bounce notifications, you need to configure your app to enable email notification and you need to create a handler to handle those incoming notifications.

There are two parts to the configuration. First, you need to enable notification. Second, you need to set the mapping between /_ah/bounce and your bounce handler, so App Engine knows where to POST the notification data. To configure your app to receive bounced email notifications:

  • Add the following to your app.yaml file to enable notification:

    See more code actions.
    inbound_services:
        - mail_bounce
    
  • Also in app.yaml, declare a mapping between /_ah/bounce and the bounce notification handler in your code, for example:

    - url: /_ah/bounce
      script: handle_bounced_email.app
      login: admin

Handling bounce notifications

A bounce notification is an automated message from an email system that there's been a problem with message delivery. In your app, you'll need to create bounce handler code to receive and process these notifications.

One way to write a bounce handler is to use the BounceNotificationHandler convenience class. If you go this route, you'll need to override its receive() method, which is called with an argument of the BounceNotification class. Whether you use the BounceNotificationHandler convenience class or not, you do need to use BounceNotification to parse the bounce notifications.

Here is a sample bounce handler that uses the BounceNotificationHandler convenience class:

@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

Learn more about the migration considerations for Mail API in the Mail handlers guide.