Sending Mail with the Mail API

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

Before you begin

Register your sender emails as authorized senders. For more information, see who can send email .

Sending email messages

To send email messages, use the JavaMail classes included with the App Engine SDK.

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, 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.

   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" 
 ); 
  
 msg 
 . 
 setText 
 ( 
 "This is a test" 
 ); 
  
 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 .