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

For more information, see Oracle®'s JavaMail API reference .

1. Sending Email Messages
2. Senders and Recipients
3. Messages and Headers
4. Multi-Part Messages
5. JavaMail Features Not Supported
6. Features of the Low-level API

Sending Email Messages

To send an email message, an app prepares a MimeMessage object, then sends it with the static method send() on the Transport class. The message is created using a JavaMail Session object. The Session and the Transport work with the App Engine Mail service without any additional configuration.

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) {
            // ...
        }

Calls to the Mail service are asynchronous, and return immediately. The Mail service manages the process of contacting the recipients' mail servers and delivering the message. If there is a problem sending the message to any recipient, or if a recipient's mail server returns a "bounce" message, the error message goes to the sender.

Senders and Recipients

Sender and recipient email addresses are represented in JavaMail using instances of the InternetAddress class. The constructor takes the email address as a string, and raises an AddressException if the address does not resemble a valid email address. Optionally, you can provide a personal name as a string for the second parameter.

To set the sender address, the app calls the setFrom() method on the MimeMessage object. The sender address must be one of the following types:

• The address of a registered administrator for the application
• The address of the user for the current request signed in with a Google Account. You can determine the current user's email address with the Users API . The user's account must be a Gmail account, or be on a domain managed by Google Apps.
• Any valid email receiving address for the app (such as [email protected]).

Several methods on the MimeMessage object establish the recipients. The addRecipient() method takes a recipient type and an address, and adds it to the list of recipients for the type. The recipient type can be any of Message.RecipientType.TO , Message.RecipientType.CC or Message.RecipientType.BCC .

You can set a "reply to" address using the setReplyTo() method.

Messages and Headers

You establish the contents of the message by calling methods on the MimeMessage object. The setSubject() method sets the subject, and the setText() method sets the (plaintext) body content.

The Mail service allows you to specify a limited set of headers on outgoing email messages. For more information about the allowed headers, see the Mail Service Overview .

Multi-Part Messages

You can send a message with file attachments, or with an HTML message body in addition to the plaintext message body, using multi-part messages. You create a MimeMultipart object to contain the parts, then create a MimeBodyPart object for each attachment or alternate message body and add it to the container. Finally, you assign the container to the MimeMessage's content.

import javax.activation.DataHandler;
import javax.mail.Multipart;
import javax.mail.internet.MimeBodyPart;
import javax.mail.internet.MimeMultipart;

// ...
        String htmlBody;        // ...
        byte[] attachmentData;  // ...

        Multipart mp = new MimeMultipart();

        MimeBodyPart htmlPart = new MimeBodyPart();
        htmlPart.setContent(htmlBody, "text/html");
        mp.addBodyPart(htmlPart);

        MimeBodyPart attachment = new MimeBodyPart();
        attachment.setFileName("manual.pdf");
        attachment.setContent(attachmentData, "application/pdf");
        mp.addBodyPart(attachment);

        message.setContent(mp);

For security purposes, message parts and attachments must be of one of several allowed types, and attachment filenames must end in a recognized filename extension for the type. For a list of allowed types and filename extensions, see Overview: Attachments .

JavaMail Features Not Supported

An app cannot use the JavaMail interface to connect to other mail services for sending or receiving email messages. SMTP configuration added to the Transport or Session is ignored.

Features of the Low-level API

All features of the low-level Mail service API are available in the JavaMail interface.

The low-level API includes a convenience method for sending mail to all of the application's administrators. To do this in JavaMail, use admins (with no at-symbol or domain) as a recipient.

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 .