Java 8 has reached end of support and will be deprecated on January 31, 2026. After deprecation, you won't be able to deploy Java 8 applications, even if your organization previously used an organization policy to re-enable deployments of legacy runtimes. Your existing Java 8 applications will continue to run and receive traffic after their deprecation date . We recommend that you migrate to the latest supported version of Java .

Receiving Email

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.

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:

 <inbound-services>  
<!--  
Used  
to  
handle  
incoming  
mail.  
-->  
<service>mail</service>  
<!--  
Used  
to  
handle  
bounced  
mail  
notifications.  
-->  
<service>mail_bounce</service>
</inbound-services>

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:

 <servlet>  
<servlet-name>mailhandler</servlet-name>  
<servlet-class>com.example.appengine.mail.MailHandlerServlet</servlet-class>
</servlet>
<servlet-mapping>  
<servlet-name>mailhandler</servlet-name>  
<url-pattern>/_ah/mail/*</url-pattern>
</servlet-mapping>
<security-constraint>  
<web-resource-collection>  
<web-resource-name>mail</web-resource-name>  
<url-pattern>/_ah/mail/*</url-pattern>  
</web-resource-collection>  
<auth-constraint>  
<role-name>admin</role-name>  
</auth-constraint>
</security-constraint>

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

  public 
  
 class 
 HandleDiscussionEmail 
  
 extends 
  
 MailHandlerBase 
  
 { 
  
 private 
  
 static 
  
 final 
  
 Logger 
  
 log 
  
 = 
  
 Logger 
 . 
 getLogger 
 ( 
 HandleDiscussionEmail 
 . 
 class 
 . 
 getName 
 ()); 
  
 public 
  
 HandleDiscussionEmail 
 () 
  
 { 
  
 super 
 ( 
 "discuss-(.*)@(.*)" 
 ); 
  
 } 
  
 @Override 
  
 protected 
  
 boolean 
  
 processMessage 
 ( 
 HttpServletRequest 
  
 req 
 , 
  
 HttpServletResponse 
  
 res 
 ) 
  
 throws 
  
 ServletException 
  
 { 
  
 log 
 . 
 info 
 ( 
 "Received e-mail sent to discuss list." 
 ); 
  
 MimeMessage 
  
 msg 
  
 = 
  
 getMessageFromRequest 
 ( 
 req 
 ); 
  
 Matcher 
  
 match 
  
 = 
  
 getMatcherFromRequest 
 ( 
 req 
 ); 
  
 // ... 
  
 return 
  
 true 
 ; 
  
 } 
 }

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

 <filter>  
<filter-name>HandleDiscussionEmail</filter-name>  
<filter-class>com.example.appengine.mail.HandleDiscussionEmail</filter-class>
</filter>
<filter-mapping>  
<filter-name>HandleDiscussionEmail</filter-name>  
<url-pattern>/_ah/mail/*</url-pattern>
</filter-mapping>

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

  public 
  
 abstract 
  
 class 
 MailHandlerBase 
  
 implements 
  
 Filter 
  
 { 
  
 private 
  
 Pattern 
  
 pattern 
  
 = 
  
 null 
 ; 
  
 protected 
  
 MailHandlerBase 
 ( 
 String 
  
 pattern 
 ) 
  
 { 
  
 if 
  
 ( 
 pattern 
  
 == 
  
 null 
  
 || 
  
 pattern 
 . 
 trim 
 (). 
 length 
 () 
  
 == 
  
 0 
 ) 
  
 { 
  
 throw 
  
 new 
  
 IllegalArgumentException 
 ( 
 "Expected non-empty regular expression" 
 ); 
  
 } 
  
 this 
 . 
 pattern 
  
 = 
  
 Pattern 
 . 
 compile 
 ( 
 "/_ah/mail/" 
 + 
 pattern 
 ); 
  
 } 
  
 @Override 
  
 public 
  
 void 
  
 init 
 ( 
 FilterConfig 
  
 config 
 ) 
  
 throws 
  
 ServletException 
  
 { 
  
 } 
  
 @Override 
  
 public 
  
 void 
  
 destroy 
 () 
  
 { 
  
 } 
  
 /** 
 * Process the message. A message will only be passed to this method 
 * if the servletPath of the message (typically the recipient for 
 * appengine) satisfies the pattern passed to the constructor. If 
 * the implementation returns false, control is passed 
 * to the next filter in the chain. If the implementation returns 
 * true, the filter chain is terminated. 
 * 
 * The Matcher for the pattern can be retrieved via 
 * getMatcherFromRequest (e.g. if groups are used in the pattern). 
 */ 
  
 protected 
  
 abstract 
  
 boolean 
  
 processMessage 
 ( 
 HttpServletRequest 
  
 req 
 , 
  
 HttpServletResponse 
  
 res 
 ) 
  
 throws 
  
 ServletException 
 ; 
  
 @Override 
  
 public 
  
 void 
  
 doFilter 
 ( 
 ServletRequest 
  
 sreq 
 , 
  
 ServletResponse 
  
 sres 
 , 
  
 FilterChain 
  
 chain 
 ) 
  
 throws 
  
 IOException 
 , 
  
 ServletException 
  
 { 
  
 HttpServletRequest 
  
 req 
  
 = 
  
 ( 
 HttpServletRequest 
 ) 
  
 sreq 
 ; 
  
 HttpServletResponse 
  
 res 
  
 = 
  
 ( 
 HttpServletResponse 
 ) 
  
 sres 
 ; 
  
 MimeMessage 
  
 message 
  
 = 
  
 getMessageFromRequest 
 ( 
 req 
 ); 
  
 Matcher 
  
 m 
  
 = 
  
 applyPattern 
 ( 
 req 
 ); 
  
 if 
  
 ( 
 m 
  
 != 
  
 null 
 && 
 processMessage 
 ( 
 req 
 , 
  
 res 
 )) 
  
 { 
  
 return 
 ; 
  
 } 
  
 chain 
 . 
 doFilter 
 ( 
 req 
 , 
  
 res 
 ); 
  
 // Try the next one 
  
 } 
  
 private 
  
 Matcher 
  
 applyPattern 
 ( 
 HttpServletRequest 
  
 req 
 ) 
  
 { 
  
 Matcher 
  
 m 
  
 = 
  
 pattern 
 . 
 matcher 
 ( 
 req 
 . 
 getServletPath 
 ()); 
  
 if 
  
 ( 
 ! 
 m 
 . 
 matches 
 ()) 
  
 m 
  
 = 
  
 null 
 ; 
  
 req 
 . 
 setAttribute 
 ( 
 "matcher" 
 , 
  
 m 
 ); 
  
 return 
  
 m 
 ; 
  
 } 
  
 protected 
  
 Matcher 
  
 getMatcherFromRequest 
 ( 
 ServletRequest 
  
 req 
 ) 
  
 { 
  
 return 
  
 ( 
 Matcher 
 ) 
  
 req 
 . 
 getAttribute 
 ( 
 "matcher" 
 ); 
  
 } 
  
 protected 
  
 MimeMessage 
  
 getMessageFromRequest 
 ( 
 ServletRequest 
  
 req 
 ) 
  
 throws 
  
 ServletException 
  
 { 
  
 MimeMessage 
  
 message 
  
 = 
  
 ( 
 MimeMessage 
 ) 
  
 req 
 . 
 getAttribute 
 ( 
 "mimeMessage" 
 ); 
  
 if 
  
 ( 
 message 
  
 == 
  
 null 
 ) 
  
 { 
  
 try 
  
 { 
  
 Properties 
  
 props 
  
 = 
  
 new 
  
 Properties 
 (); 
  
 Session 
  
 session 
  
 = 
  
 Session 
 . 
 getDefaultInstance 
 ( 
 props 
 , 
  
 null 
 ); 
  
 message 
  
 = 
  
 new 
  
 MimeMessage 
 ( 
 session 
 , 
  
 req 
 . 
 getInputStream 
 ()); 
  
 req 
 . 
 setAttribute 
 ( 
 "mimeMessage" 
 , 
  
 message 
 ); 
  
 } 
  
 catch 
  
 ( 
 MessagingException 
  
 e 
 ) 
  
 { 
  
 throw 
  
 new 
  
 ServletException 
 ( 
 "Error processing inbound message" 
 , 
  
 e 
 ); 
  
 } 
  
 catch 
  
 ( 
 IOException 
  
 e 
 ) 
  
 { 
  
 throw 
  
 new 
  
 ServletException 
 ( 
 "Error processing inbound message" 
 , 
  
 e 
 ); 
  
 } 
  
 } 
  
 return 
  
 message 
 ; 
  
 } 
 }

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:

  import 
  
 java.io.IOException 
 ; 
 import 
  
 java.util.logging.Logger 
 ; 
 import 
  
 java.util.Properties 
 ; 
 import 
  
 javax.mail.MessagingException 
 ; 
 import 
  
 javax.mail.Session 
 ; 
 import 
  
 javax.mail.internet.MimeMessage 
 ; 
 import 
  
 javax.servlet.http.HttpServlet 
 ; 
 import 
  
 javax.servlet.http.HttpServletRequest 
 ; 
 import 
  
 javax.servlet.http.HttpServletResponse 
 ; 
 public 
  
 class 
 MailHandlerServlet 
  
 extends 
  
 HttpServlet 
  
 { 
  
 private 
  
 static 
  
 final 
  
 Logger 
  
 log 
  
 = 
  
 Logger 
 . 
 getLogger 
 ( 
 MailHandlerServlet 
 . 
 class 
 . 
 getName 
 ()); 
  
 @Override 
  
 public 
  
 void 
  
 doPost 
 ( 
 HttpServletRequest 
  
 req 
 , 
  
 HttpServletResponse 
  
 resp 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 Properties 
  
 props 
  
 = 
  
 new 
  
 Properties 
 (); 
  
 Session 
  
 session 
  
 = 
  
 Session 
 . 
 getDefaultInstance 
 ( 
 props 
 , 
  
 null 
 ); 
  
 try 
  
 { 
  
 MimeMessage 
  
 message 
  
 = 
  
 new 
  
 MimeMessage 
 ( 
 session 
 , 
  
 req 
 . 
 getInputStream 
 ()); 
  
 log 
 . 
 info 
 ( 
 "Received mail message." 
 ); 
  
 } 
  
 catch 
  
 ( 
 MessagingException 
  
 e 
 ) 
  
 { 
  
 // ... 
  
 } 
  
 // ... 
  
 } 
 }

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.