Sending Mail with the Mail API

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

Sending email messages

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

When you create a JavaMail Session, if you do not provide any SMTP server configuration, App Engine uses the Mail service for sending messages. Alternatively, you can add SMTP configuration for supported third-party mail providers such as Mailgun, Mailjet, or SendGrid.

To send a message:

  1. Create a message using a JavaMail Session object.

  2. Create a MimeMessage object.

  3. To set the message sender and recipient, use the InternetAddress class.

    1. Identify the sender by calling the setFrom() method on the MimeMessage object. Optionally, you can provide a personal name as a string in the second parameter. For more information on which email addresses you can use as the sender address, see Who can send mail.

    2. Identify the recipient by passing a recipient type and an address to the addRecipient() method. The recipient type can be Message.RecipientType.TO, Message.RecipientType.CC or Message.RecipientType.BCC.

    The InternetAddress constructor raises an AddressException if the email address appears to be invalid.

  4. To set a "reply to" address, use the setReplyTo() method.

  5. Establish the contents of the message by calling methods on the MimeMessage object. Set the subject with setSubject() and set the plaintext body content with setText().

  6. To send the message, use the static method send() on the Transport class.

The Mail service allows you to specify a limited set of headers on outgoing email messages. For more information, see Optional headers you can use.

The following code sample demonstrates how to send mail:

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

try {
  Message msg = new MimeMessage(session);
  msg.setFrom(new InternetAddress("admin@example.com", "Example.com Admin"));
  msg.addRecipient(Message.RecipientType.TO,
                   new InternetAddress("user@example.com", "Mr. User"));
  msg.setSubject("Your Example.com account has been activated");
  Transport.send(msg);
} catch (AddressException e) {
  // ...
} catch (MessagingException e) {
  // ...
} catch (UnsupportedEncodingException 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.

Sending multi-part messages

You can send multi-part messages, such as a message with file attachments, or a message with a plaintext message body and an HTML message body.

To send a multi-part message:

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

  2. Assign the container to the content for MimeMessage.

The following code sample demonstrates how to send a multi-part message:

String htmlBody = "";          // ...
byte[] attachmentData = null;  // ...
Multipart mp = new MimeMultipart();

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

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

msg.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 Mail with attachments.

Send feedback about...