receiving mail with mail api

Receiving mail with the Mail API

This guide describes how to use the Mail API to receive mail.

Email messages are sent to your app as HTTP requests. To process incoming email messages, you must associate email addresses with servlets in your application configuration, and then include the servlet code with your app. The incoming email generates HTTP requests that are passed to the appropriate servlets for handling.

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.

Before you begin

You must register your sender emails as authorized senders. For more information, see who can send email.

Receiving mail

You can set up your app to receive incoming email at addresses in the following format:

anything@appid.appspotmail.com

Note: Even if your app is deployed on a custom domain, you can't receive email sent to addresses in that domain.

To receive email:

1. Enable incoming mail in your app's app.yaml file:

2. Set up a handler to process incoming emails, which are supplied to your app as MIME data in an HTTP POST request.

   1. In your app, register a handler to the /_ah/mail/ path:

   2. In the handler, read the email's data from the *http.Request:

   You can use the net/mail package in the standard library to parse mail messages.

3. Enable incoming mail in your app's app.yaml file. Add the following to the inbound_services:

4. In your configuration file, create mappings from URL paths that represent email addresses to handlers in your app's code. The pattern /_ah/mail/.+ matches all incoming email addresses:

5. Implement code for the handlers you specified in your application code.

   You can read the MIME data from [php://input][input] and parse the email content using [Mailparse][parse].

[input]: https://php.net/manual/en/wrappers.php.php#wrappers.php.input [parse]: http://php.net/manual/en/book.mailparse.php

Learn more about the migration considerations for the Mail API in the Accessing legacy bundled services for PHP guide.

Configuring your application to receive email

When you create a new application, incoming email is disabled by default. If you don't explicitly enable incoming email messages sent to your app are ignored.

To enable the incoming email service, modify the appengine-web.xml and web.xml configuration files:

Enabling email in appengine-web.xml

Modify appengine-web.xml by adding an inbound-services section that enables the incoming email service:

View appengine-web.xml on GitHub (region: handle_incoming_mail)

Email messages are sent to your app as HTTP POST requests using the following URL:

/_ah/mail/<ADDRESS>

where <ADDRESS> is a full email address, including domain name. Note that even if your app is deployed on a custom domain, your app can't receive email sent to addresses in that domain.

Enabling email in web.xml

Modify web.xml by mapping email URLs to servlets:

View web.xml on GitHub (region: incoming_mail_servlet)

In the above snippets, /_ah/mail/* matches all email addressed to the app. Mail servlets run in the currently serving version of your app in App Engine.

Pattern-based dispatching of incoming messages

If your app uses pattern matching, consider using a filter-based approach based on the following code snippets.

Concrete handler

View HandleDiscussionEmail.java on GitHub (region: example)

The above concrete handler is registered using the following snippet in web.xml:

View web.xml on GitHub (region: filter_handler)

Note that security-constraint directives are not possible on filters; security policies on the handler will have to be introduced some other way.

Abstract handler

View MailHandlerBase.java on GitHub (region: example)

Handling incoming email

The JavaMail API includes the MimeMessage class which you can use to parse incoming email messages. MimeMessage has a constructor that accepts a java.io.InputStream and a JavaMail session, which can have an empty configuration.

Create a MimeMessage instance like this:

View MailHandlerServlet.java on GitHub (region: mail_handler_servlet)

You can then use various methods to parse the message object:

• Call getFrom() to return the sender of the message.
• Call getContentType() to extract the message content type. The getContent() method returns an object that implements the Multipart interface.
• Call getCount() to determine the number of parts
• Call getBodyPart(int index) to return a particular body part.

After you set up your app to handle incoming email, you can use the development server console to simulate incoming email messages. To learn more, including how to start the development server, see The Java Development Server. After you start your application in the local development server, you can access your application by visiting the URL http://localhost:8888/_ah/admin/, replacing the value 8888 with whatever port you are using if you don't use the default port for the local development server.

In the development server, click Inbound Mail on the left side, fill out the form that appears, and click Send Email.

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.

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

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

When using Python web frameworks, the InboundEmailMessage constructor takes in the bytes of the HTTP request body. There are multiple ways to create the InboundEmailMessage object in Python. In Flask, request.get_data() gives the request bytes. The InboundEmailMessage object 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 of Attachment objects, possibly empty.
• original is the complete message, including data not exposed by the other fields such as email headers, as a Python email.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:

1. Access the development server as an administrator by going to http://localhost:8080/console and selecting Sign in as administrator.

2. In the development server, click Inbound Mail in the navigation.

3. Fill out the form that appears, and click Send Email.

   To get the development server running, see the local development server.

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