Skip to page content Skip to main navigation
English | Site Directory

e.g. "templates" or "datastore"

# Using JavaMail

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

For more information, see Sun's JavaMail API reference.

- Sending Email Messages
- Senders and Recipients
- Messages and Headers
- Multi-Part Messages
- JavaMail Features Not Supported
- 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.AddressException;
    import javax.mail.InternetAddress;
    import javax.mail.MessagingException;
    import javax.mail.MimeMessage;
    import javax.mail.Message;
    import javax.mail.Session;
    import javax.mail.Transport;

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

            String msgBody = "...";

            try {
                Message msg = new MimeMessage(session);
                msg.setFrom(new InternetAddress("admin@example.com"));
                msg.addRecipient(Message.RecipientType.TO,
                                 new InternetAddress("user@example.com"));
                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.

To set the sender address, the app calls the `setFrom()` method on the MimeMessage object. The sender must be either the address of a registered developer for the application, or the address of the user for the current request signed in with a Google Account.

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.

For security purposes, the Mail service does not allow arbitrary headers on outgoing email messages. Some headers are overridden by the Mail service, such as the message send date. Other headers added to the outgoing message are stripped.

## 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.mail.MimeBodyPart;
    import javax.mail.MimeMultipart;
    import javax.mail.Multipart;
    import javax.activation.DataHandler;

    // ...
            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 receive email messages.

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 `admin@.` ("admin", an at-symbol, and a period) as a recipient.