Mail Java API Overview

Python | Java | PHP | Go

App Engine applications can send email messages on behalf of the app's administrators, and on behalf of users with Google Accounts. Apps can receive email at various addresses. Apps send messages using the Mail service and receive messages in the form of HTTP requests initiated by App Engine and posted to the app.

Sending mail with the JavaMail API

The Mail service Java API supports the JavaMail ( javax.mail ) interface for sending email messages.

All of the JavaMail classes you need are included with the App Engine SDK. Do not add Oracle®'s JavaMail JARs to your app; if you do, the app will throw exceptions.

When creating a JavaMail Session, you do not need to provide any SMTP server configuration. App Engine will always use the Mail service for sending messages.

import java.util.Properties;
import javax.mail.Message;
import javax.mail.MessagingException;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.AddressException;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;

// ...
Properties props = new Properties();
Session session = Session.getDefaultInstance(props, null);

String msgBody = "...";

try {
    Message msg = new MimeMessage(session);
    msg.setFrom(new InternetAddress("[email protected]", "Example.com Admin"));
    msg.addRecipient(Message.RecipientType.TO,
     new InternetAddress("[email protected]", "Mr. User"));
    msg.setSubject("Your Example.com account has been activated");
    msg.setText(msgBody);
    Transport.send(msg);

} catch (AddressException e) {
    // ...
} catch (MessagingException e) {
    // ...
}

Receiving mail in Java

You can set up your app to receive incoming email at [email protected] addresses. To receive email, you put a section that enables incoming mail in your app's appengine-web.xml file:

<inbound-services>
  <service>mail</service>
</inbound-services>

Incoming email in App Engine works by posting HTTP requests containing MIME data to your app. The email's MIME data is supplied to your app as the contents of an HTTP POST request, and you process this data in your handler.

In your web.xml file, you must create mappings from URL paths that represent email addresses to handlers in your app's code:

<servlet>
  <servlet-name>mailhandler</servlet-name>
  <servlet-class>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>

The URL path is /_ah/mail/ followed by the incoming email address used. The pattern /_ah/mail/* matches all incoming email addresses.

In your app, create the servlet class to handle incoming mail requests. The JavaMail API includes the MimeMessage class which you can use to parse email messages in your handlers:

import java.io.IOException; 
import java.util.Properties; 
import javax.mail.Session; 
import javax.mail.internet.MimeMessage; 
import javax.servlet.http.*; 

public class MailHandlerServlet extends HttpServlet { 
    @Override
    public void doPost(HttpServletRequest req, HttpServletResponse resp) 
            throws IOException { 
                Properties props = new Properties(); 
                Session session = Session.getDefaultInstance(props, null); 
                MimeMessage message = new MimeMessage(session, req.getInputStream());

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

Sending mail

The Mail service can send email messages to one or more recipients. The message contains a subject, a plaintext body, and an optional HTML body. It can also contain file attachments, as well as a limited set of headers.

For security purposes, the sender address of a message must be the email address of an administrator for the application or any valid email receiving address for the app (see Receiving Mail ). The sender can also be the Google Account email address of the current user who is signed in, if the user's account is a Gmail account or is on a domain managed by Google Apps.

If you want to send email on behalf of the application but do not want to use a single administrator's personal Google Account as the sender, you can create a new Google Account for the application using any valid email address, then add the new account as an administrator for the application. To add an account as an administrator, see the "Permissions" section of the Admin Console . Accounts must be given "Owner" or "Developer" level access when added.

You can also send mail using a domain account by adding the domain account under "Permissions" in the Admin Console . Domain accounts are accounts outside of the Google domain with email addresses that do not end in @gmail.com or @APP-ID.appspotmail.com. You should set the SPF records for your domain to indicate that Google is a trusted source for your email. For instructions on how to do this, see SPF records in the Google Apps help articles.

You can use any email address for a recipient. A recipient can be in the message's "to" field or the "cc" field, or the recipient can be hidden from the message header (a "blind carbon copy" or "bcc").

When an application calls the Mail service to send a message, the message is queued and the call returns immediately. The Mail service uses standard procedures for contacting each recipient's mail server, delivering the message, and retrying if the mail server cannot be contacted.

If the Mail service cannot deliver a message, or if an recipient's mail server returns a bounce message (such as if there is no account for that address on that system), the error message is sent by email to the address of the sender for the message. The application itself does not receive any notification about whether delivery succeeded or failed.

Receiving mail

Your app can receive email at addresses of the following form:

[email protected]

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

Email messages are sent to your app as HTTP requests. These requests are generated by App Engine and posted to your app. In your app's configuration, you specify handlers that will be called to handle these HTTP requests. The handlers run in the default module (or application version). They receive the MIME data for email messages, which you then parse into its individual fields.

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.

The ability to receive mail in your app is disabled by default. To enable your app to receive mail, you must specify that you want this service enabled in your appengine-web.xml file by including this:

<inbound-services>
  <service>mail</service>
</inbound-services>

Receiving bounce notification

By default, apps do not receive email bounce notifications. To turn this on for your app and to handle bounce notifications, see Receiving Bounce Notification .

Sending mail with attachments

An outgoing email message can have zero or more file attachments.

An attachment has a filename and file data. The file data can come from any source, such as an application data file or the datastore. The MIME type of the attachment is determined from the filename.

The following is a list of MIME types and their corresponding filename extensions allowed for file attachments to an email message. You are not limited to these extensions. If you use an unknown extension, App Engine will assign it the mime type application/octet-stream .

MIME Type	Filename Extension(s)
application/msword	doc
application/msword	docx
application/pdf	pdf
application/rss+xml	rss
application/vnd.google-earth.kml+xml	kml
application/vnd.google-earth.kmz	kmz
application/vnd.ms-excel	xls
application/vnd.ms-excel	xlsx
application/vnd.ms-powerpoint	pptx
application/vnd.ms-powerpoint	pps ppt
application/vnd.oasis.opendocument.presentation	odp
application/vnd.oasis.opendocument.spreadsheet	ods
application/vnd.oasis.opendocument.text	odt
application/vnd.sun.xml.calc	sxc
application/vnd.sun.xml.writer	sxw
application/x-gzip	gzip
application/zip	zip
audio/basic	au snd
audio/flac	flac
audio/mid	mid rmi
audio/mp4	m4a
audio/mpeg	mp3
audio/ogg	oga ogg
audio/x-aiff	aif aifc aiff
audio/x-wav	wav
image/gif	gif
image/jpeg	jpeg jpg jpe
image/png	png
image/tiff	tiff tif
image/vnd.wap.wbmp	wbmp
image/x-ms-bmp	bmp
text/calendar	ics
text/comma-separated-values	csv
text/css	css
text/html	htm html
text/plain	text txt asc diff pot
text/x-vcard	vcf
video/mp4	mp4
video/mpeg	mpeg mpg mpe
video/ogg	ogv
video/quicktime	qt mov
video/x-msvideo	avi

As a security measure to protect against viruses, you cannot send email attachments or zip files containing any of the following extensions:

Sending mail with headers

An outgoing email can have zero or more extra headers. A header has a name and a value.

For security purposes, the name of a header must be of one of the allowed header names:

In-Reply-To
List-Id
List-Unsubscribe
On-Behalf-Of
References
Resent-Date
Resent-From
Resent-To

Mail and the development server

When an application running in the development server calls the Mail service to send an email message, the message is printed to the log. The Java development server does not send the email message.

Authenticating mail: DKIM

If your application sends messages from an email address that is part of a Google Apps domain, App Engine can utilize a Google Apps feature to cryptographically sign the emails it sends. This signature says that this mail that purports to be from [email protected] really came from example.com . The recipient can check this signature; if the signature is there and correct, the recipient knows that the sender's domain wasn't spoofed. App Engine uses the DomainKeys Identified Mail (DKIM) standard to authenticate the sender's domain.

To enable DKIM authentication for messages sent from Google Apps email addresses, follow these instructions in the Google Apps Help Center. Note that it may take up to 48 hours before DKIM authentication is active for your Google Apps domain.

App Engine will sign the application's outgoing mails if the sender address is part of a Google Apps domain with DKIM enabled. Additionally, the sender address must be formatted such that the domain part of the email address only consists of lowercase letters.

Bulk senders guidelines

You must follow the guidelines in this section if your application is sending out bulk email, i.e. similar messages to numerous recipients. These guidelines will help to improve your inbox delivery rate to Gmail users, by ensuring that all recipients in your distribution list actually want to receive the email. If recipients manually mark your email as spam then that acts as a strong signal to Gmail to mark future emails from you as spam.

Authentication and identification

Use the same sender for every bulk email. When calling the Mail API function to send email, the From header will be set to match the sender you specify.
Your sender address should be an account in a Google Apps for Business domain. Google accounts that send too many emails that are marked as spam by Google, can be temporarily disabled if their domain is still in the free trial period or has less than six users. In these cases, the Mail API will throw an exception with an Unauthorized sender error message.
Sign your email with DKIM , which requires a Google Apps domain if you are sending using App Engine.
Publish an SPF record to prevent spammers from spoofing your envelope sender address. SPF verifies that email is sent from an IP address that is published in the DNS records of the envelope sender. App Engine's envelope sender is in the apphosting.bounces.google.com domain, so your SPF record may not be used to determine if email from App Engine should be delivered.

Sending limits

Your Mail quota is shown in the Quota Details page in the Admin Console. The quota is reset daily. You will get an over quota exception if you exceed the daily quota. See the Quotas and Limits section for more details. To request a quota increase, go to the Quotas documentation page .
You should throttle sending of emails to avoid sending too many emails in a short burst, which could cause some emails to be silently dropped due to a safety limit on Google's side. You can calculate the maximum daily rate of sending emails per second by dividing your daily quota by 86,400, the number of seconds in a day. We recommend that you do not send bulk email with short bursts at higher than 50 times this long term rate.

Subscription

Each user in your distribution list should opt-in to receive messages from you in one of the following ways:
- By sending you an email asking to subscribe
- By manually checking a box on a web form, or within a piece of software
Using an email address list purchased from a third-party is not considered opt-in. You also should not set a checkbox on a web form or within a piece of software to subscribe all users by default. Users should not be required to explicitly opt-out of mailings.
You should verify that the person that signed up by checking the box on the web form or in software is actually receiving emails at the address that was specified in the form, by sending an email that requires them to confirm receipt.

Unsubscribing

A user must be able to unsubscribe in one of the following ways:
- Through a prominent link in the email with no further user interaction other than confirmation
- Via an email unsubscribe response
App Engine can only receive email sent to the appid.appspotmail domain. Therefore, you will need to set your sender to an address in this domain if you want to automatically handle email unsubscribe responses within App Engine.
Use the List-Unsubscribe header, which is supported by the App Engine Mail API .
Automatically unsubscribe users whose addresses bounce multiple pieces of email. You can configure your app to receive bounce notifications .
Periodically send email confirmations to users, offering the opportunity to unsubscribe from each list they are signed up for.
You should explicitly indicate the email address subscribed within your email because users may forward email from other accounts.

Format

Format to RFC 2822 SMTP standards and, if using HTML, w3.org standards .
Attempts to hide the true sender of the message or the true landing page for any web links in the message may result in non-delivery. For example, we recommend that you do not use URL shortener services in bulk email, since these can mask the real URLs contained in the body of your email.
The subject of each message should be relevant to the body's content and not be misleading.

Delivery

The following factors will help messages arrive in Gmail users' inboxes:
- The From address is listed in the user's Contacts list.
- A user clicks "Not Spam" to alert Gmail that messages sent from that address are solicited.
If you send both promotional email and transactional email relating to your organization, we recommend separating email by purpose as much as possible. You can do this by:
- Using separate email addresses for each function.
- Sending email from different domains for each function.

Third-party senders

If others use your service to send email, you are responsible for monitoring your users and/or clients' behavior. You must terminate, in a timely fashion, all users and/or clients who use your service to send spam email. The Google Cloud Platform Acceptable Use Policy specifically prohibits spam. Your application can be suspended if you violate this policy, as described in the Google Cloud Platform Terms of Service .
You must have an email address available for users and/or clients to report abuse, which should normally be [email protected] . You should also monitor [email protected] .
Monitor email sent to app admins. Google may need to urgently contact app admins, for example to notify you of a violation of the Acceptable Use Policy. We can help you to resolve the problems more quickly if you respond promptly to our emails.
You must maintain up-to-date contact information in your WHOIS record maintained by your domain registrar, and on abuse.net .

Affiliate marketing programs

Affiliate marketing programs reward third-parties for bringing visitors to your site. These programs are attractive to spammers and can potentially do more harm than good. Please note the following:
- If your brand becomes associated with affiliate marketing spam, it can affect the email sent by you and your other affiliates.
- It is your responsibility to monitor your affiliates and remove them if they send spam.

Alternatives to the App Engine Mail API

You can use a third-party email delivery service provider to send email from App Engine. These services may provide additional features that are not available in the Mail API and may be a better solution for some bulk email senders.
You can use the Sockets API to connect directly to an IMAP server to send email.

Quotas and limits

Each Mail service request counts toward the Mail API Calls quota.

Each recipient email address for an email message counts toward the Recipients Emailed (billable) quota. Each recipient that is an administrator for the application also counts toward the Admins Emailed quota.

Data sent in the body of an email message counts toward the following quotas:

Outgoing Bandwidth (billable)
Message Body Data Sent

Each attachment included with an email message counts toward the Attachments Sent quota.

Data sent as an attachment to an email message counts toward the following quotas:

Outgoing Bandwidth (billable)
Attachment Data Sent

For more information on quotas, see Quotas , and the "Quota Details" section of the Admin Console .

In addition to quotas, the following limits apply to the use of the Mail service:

Limit	Amount
maximum size of outgoing mail messages, including attachments	10 megabytes
maximum size of incoming mail messages, including attachments	10 megabytes
maximum size of message when an administrator is a recipient	16 kilobytes

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Last updated July 16, 2014.

Java