Email messages sent to your app are implemented as HTTP requests containing MIME data. To process incoming email messages, you associate email addresses with script handlers in your app configuration, then include the handlers in your app's code.
Incoming email generates HTTP requests, which are passed to the appropriate scripts. The scripts that handle the incoming email must reside in your default service.
For more information on the Mail service, see the Mail API Overview.
Configuring your application to receive email
When you create a new app, incoming email is disabled by default. To enable the
incoming email, you must modify your app.yaml
file in your default service.
Add an
inbound_services
section that enables the incoming email service. For example:If you don't enable incoming email by including this section in your configuration file, then incoming email is disabled, and email messages sent to the app are ignored.
Add mappings that associate URL-mapped email addresses with script handlers.
For the default service, the email address for receiving email has the following format:
[STRING]@[Google Cloud project ID].appspotmail.com
For non-default services, the email address has the following format:
[STRING]@[servicename]-dot-[Google Cloud project ID].appspotmail.com
Email messages are sent to your app as HTTP POST requests using the following URL, where [ADDRESS] is a full email address, including domain name:
/_ah/mail/[ADDRESS]
To handle incoming email in your app, map email URLs to handlers in the
app.yaml
file:In the above example,
/_ah/mail/.+
matches all email addressed to the app. If you prefer, you can set up multiple handlers for different email addresses, as in the following example:URLs of incoming email messages are matched to this list from first to last, so if an email message URL matches more than one pattern, the first matching handler will be the one executed. This allows you to include a "catchall" handler as the last mapping. The handlers run in the default module (or application version).
Handling incoming email
The Python SDK defines InboundMailHandler
, a webapp class for handling
incoming email. InboundMailHandler
is in the
google.appengine.ext.webapp.mail_handlers
package.
To use InboundMailHandler
:
- Create a subclass for
InboundMailHandler
and override thereceive()
method. - Call the
receive()
method with an argument of classInboundEmailMessage
, defined by the Python SDK.
For example, you can create an instance of InboundEmailMessage
like this:
InboundMailHandler
contains a mapping()
convenience class method that
returns a pair matching all incoming email addresses to the mail handler and of
course you can call it on any subclass of InboundMailHandler
you code:
The InboundEmailMessage
object (mail_message
in this example) contains the
email message. Its bodies()
method returns the bodies within the message. If
you call bodies()
without arguments, it returns an iterator that yields HTML
bodies first, then plain text bodies. If you want just HTML or just plain text,
you can pass an argument to bodies()
:
The InboundEmailMessage
object includes attributes to access other message
fields:
subject
contains the message subject.sender
is the sender's address e.g."Nobody <nobody@example.com>"
.to
is a comma-separated list of the message's primary recipients e.g."Joe <joe@example.com>, Bill <bill@example.com>"
.cc
contains a comma-separated list of the cc recipients e.g."Joe <joe@example.com>, Bill <bill@example.com>"
.date
returns the message date.attachments
is a list ofAttachment
objects, possibly empty.original
is the complete message, including data not exposed by the other fields such as email headers, as a Pythonemail.message.Message
.
Simulating incoming messages with the local development server
Once you set up your app to handle incoming email, you can use the development server console to simulate incoming email messages:
- Access the development server as an administrator by going to http://localhost:8080/console and selecting Sign in as administrator.
- In the development server, click Inbound Mail in the navigation.
Fill out the form that appears, and click Send Email.
To learn more, including how to get the development server running, see the Python Development Server.