org.springframework.mail.javamail

Class MimeMessageHelper

  • java.lang.Object
    • org.springframework.mail.javamail.MimeMessageHelper


  • public class MimeMessageHelper
    extends java.lang.Object
    Helper class for populating a MimeMessage.

    Mirrors the simple setters of SimpleMailMessage, directly applying the values to the underlying MimeMessage. Allows for defining a character encoding for the entire message, automatically applied by all methods of this helper class.

    Offers support for HTML text content, inline elements such as images, and typical mail attachments. Also supports personal names that accompany mail addresses. Note that advanced settings can still be applied directly to the underlying MimeMessage object!

    Typically used in MimeMessagePreparator implementations or JavaMailSender client code: simply instantiating it as a MimeMessage wrapper, invoking setters on the wrapper, using the underlying MimeMessage for mail sending. Also used internally by JavaMailSenderImpl.

    Sample code for an HTML mail with an inline image and a PDF attachment:

     mailSender.send(new MimeMessagePreparator() {
       public void prepare(MimeMessage mimeMessage) throws MessagingException {
         MimeMessageHelper message = new MimeMessageHelper(mimeMessage, true, "UTF-8");
         message.setFrom("[email protected]");
         message.setTo("[email protected]");
         message.setSubject("my subject");
         message.setText("my text <img src='cid:myLogo'>", true);
         message.addInline("myLogo", new ClassPathResource("img/mylogo.gif"));
         message.addAttachment("myDocument.pdf", new ClassPathResource("doc/myDocument.pdf"));
       }
     });
    Consider using MimeMailMessage (which implements the common MailMessage interface, just like SimpleMailMessage) on top of this helper, in order to let message population code interact with a simple message or a MIME message through a common interface.

    Warning regarding multipart mails: Simple MIME messages that just contain HTML text but no inline elements or attachments will work on more or less any email client that is capable of HTML rendering. However, inline elements and attachments are still a major compatibility issue between email clients: It's virtually impossible to get inline elements and attachments working across Microsoft Outlook, Lotus Notes and Mac Mail. Consider choosing a specific multipart mode for your needs: The javadoc on the MULTIPART_MODE constants contains more detailed information.

    Since:
    19.01.2004
    Author:
    Juergen Hoeller
    See Also:
    setText(String, boolean), setText(String, String), addInline(String, org.springframework.core.io.Resource), addAttachment(String, org.springframework.core.io.InputStreamSource), MULTIPART_MODE_MIXED_RELATED, MULTIPART_MODE_RELATED, getMimeMessage(), JavaMailSender
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static int MULTIPART_MODE_MIXED
      Constant indicating a multipart message with a single root multipart element of type "mixed".
      static int MULTIPART_MODE_MIXED_RELATED
      Constant indicating a multipart message with a root multipart element "mixed" plus a nested multipart element of type "related".
      static int MULTIPART_MODE_NO
      Constant indicating a non-multipart message.
      static int MULTIPART_MODE_RELATED
      Constant indicating a multipart message with a single root multipart element of type "related".
    • Constructor Summary

      Constructors 
      Constructor and Description
      MimeMessageHelper(MimeMessage mimeMessage)
      Create a new MimeMessageHelper for the given MimeMessage, assuming a simple text message (no multipart content, i.e.
      MimeMessageHelper(MimeMessage mimeMessage, boolean multipart)
      Create a new MimeMessageHelper for the given MimeMessage, in multipart mode (supporting alternative texts, inline elements and attachments) if requested.
      MimeMessageHelper(MimeMessage mimeMessage, boolean multipart, java.lang.String encoding)
      Create a new MimeMessageHelper for the given MimeMessage, in multipart mode (supporting alternative texts, inline elements and attachments) if requested.
      MimeMessageHelper(MimeMessage mimeMessage, int multipartMode)
      Create a new MimeMessageHelper for the given MimeMessage, in multipart mode (supporting alternative texts, inline elements and attachments) if requested.
      MimeMessageHelper(MimeMessage mimeMessage, int multipartMode, java.lang.String encoding)
      Create a new MimeMessageHelper for the given MimeMessage, in multipart mode (supporting alternative texts, inline elements and attachments) if requested.
      MimeMessageHelper(MimeMessage mimeMessage, java.lang.String encoding)
      Create a new MimeMessageHelper for the given MimeMessage, assuming a simple text message (no multipart content, i.e.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method and Description
      void addAttachment(java.lang.String attachmentFilename, DataSource dataSource)
      Add an attachment to the MimeMessage, taking the content from a javax.activation.DataSource.
      void addAttachment(java.lang.String attachmentFilename, java.io.File file)
      Add an attachment to the MimeMessage, taking the content from a java.io.File.
      void addAttachment(java.lang.String attachmentFilename, InputStreamSource inputStreamSource)
      Add an attachment to the MimeMessage, taking the content from an org.springframework.core.io.InputStreamResource.
      void addAttachment(java.lang.String attachmentFilename, InputStreamSource inputStreamSource, java.lang.String contentType)
      Add an attachment to the MimeMessage, taking the content from an org.springframework.core.io.InputStreamResource.
      void addBcc(InternetAddress bcc) 
      void addBcc(java.lang.String bcc) 
      void addBcc(java.lang.String bcc, java.lang.String personal) 
      void addCc(InternetAddress cc) 
      void addCc(java.lang.String cc) 
      void addCc(java.lang.String cc, java.lang.String personal) 
      void addInline(java.lang.String contentId, DataSource dataSource)
      Add an inline element to the MimeMessage, taking the content from a javax.activation.DataSource.
      void addInline(java.lang.String contentId, java.io.File file)
      Add an inline element to the MimeMessage, taking the content from a java.io.File.
      void addInline(java.lang.String contentId, InputStreamSource inputStreamSource, java.lang.String contentType)
      Add an inline element to the MimeMessage, taking the content from an org.springframework.core.InputStreamResource, and specifying the content type explicitly.
      void addInline(java.lang.String contentId, Resource resource)
      Add an inline element to the MimeMessage, taking the content from a org.springframework.core.io.Resource.
      void addTo(InternetAddress to) 
      void addTo(java.lang.String to) 
      void addTo(java.lang.String to, java.lang.String personal) 
      protected DataSource createDataSource(InputStreamSource inputStreamSource, java.lang.String contentType, java.lang.String name)
      Create an Activation Framework DataSource for the given InputStreamSource.
      protected void createMimeMultiparts(MimeMessage mimeMessage, int multipartMode)
      Determine the MimeMultipart objects to use, which will be used to store attachments on the one hand and text(s) and inline elements on the other hand.
      protected java.lang.String getDefaultEncoding(MimeMessage mimeMessage)
      Determine the default encoding for the given MimeMessage.
      protected FileTypeMap getDefaultFileTypeMap(MimeMessage mimeMessage)
      Determine the default Java Activation FileTypeMap for the given MimeMessage.
      java.lang.String getEncoding()
      Return the specific character encoding used for this message, if any.
      FileTypeMap getFileTypeMap()
      Return the FileTypeMap used by this MimeMessageHelper.
      MimeMessage getMimeMessage()
      Return the underlying MimeMessage object.
      MimeMultipart getMimeMultipart()
      Return the underlying MIME "multipart/related" object, if any.
      MimeMultipart getRootMimeMultipart()
      Return the root MIME "multipart/mixed" object, if any.
      boolean isMultipart()
      Return whether this helper is in multipart mode, i.e.
      boolean isValidateAddresses()
      Return whether this helper will validate all addresses passed to it.
      void setBcc(InternetAddress bcc) 
      void setBcc(InternetAddress[] bcc) 
      void setBcc(java.lang.String bcc) 
      void setBcc(java.lang.String[] bcc) 
      void setCc(InternetAddress cc) 
      void setCc(InternetAddress[] cc) 
      void setCc(java.lang.String cc) 
      void setCc(java.lang.String[] cc) 
      void setFileTypeMap(FileTypeMap fileTypeMap)
      Set the Java Activation Framework FileTypeMap to use for determining the content type of inline content and attachments that get added to the message.
      void setFrom(InternetAddress from) 
      void setFrom(java.lang.String from) 
      void setFrom(java.lang.String from, java.lang.String personal) 
      protected void setMimeMultiparts(MimeMultipart root, MimeMultipart main)
      Set the given MimeMultipart objects for use by this MimeMessageHelper.
      void setPriority(int priority)
      Set the priority ("X-Priority" header) of the message.
      void setReplyTo(InternetAddress replyTo) 
      void setReplyTo(java.lang.String replyTo) 
      void setReplyTo(java.lang.String replyTo, java.lang.String personal) 
      void setSentDate(java.util.Date sentDate)
      Set the sent-date of the message.
      void setSubject(java.lang.String subject)
      Set the subject of the message, using the correct encoding.
      void setText(java.lang.String text)
      Set the given text directly as content in non-multipart mode or as default body part in multipart mode.
      void setText(java.lang.String text, boolean html)
      Set the given text directly as content in non-multipart mode or as default body part in multipart mode.
      void setText(java.lang.String plainText, java.lang.String htmlText)
      Set the given plain text and HTML text as alternatives, offering both options to the email client.
      void setTo(InternetAddress to) 
      void setTo(InternetAddress[] to) 
      void setTo(java.lang.String to) 
      void setTo(java.lang.String[] to) 
      void setValidateAddresses(boolean validateAddresses)
      Set whether to validate all addresses which get passed to this helper.
      protected void validateAddress(InternetAddress address)
      Validate the given mail address.
      protected void validateAddresses(InternetAddress[] addresses)
      Validate all given mail addresses.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • MULTIPART_MODE_NO

        public static final int MULTIPART_MODE_NO
        Constant indicating a non-multipart message.
        See Also:
        Constant Field Values
      • MULTIPART_MODE_MIXED

        public static final int MULTIPART_MODE_MIXED
        Constant indicating a multipart message with a single root multipart element of type "mixed". Texts, inline elements and attachements will all get added to that root element.

        This was Spring 1.0's default behavior. It is known to work properly on Outlook. However, other mail clients tend to misinterpret inline elements as attachments and/or show attachments inline as well.

        See Also:
        Constant Field Values
      • MULTIPART_MODE_RELATED

        public static final int MULTIPART_MODE_RELATED
        Constant indicating a multipart message with a single root multipart element of type "related". Texts, inline elements and attachements will all get added to that root element.

        This was the default behavior from Spring 1.1 up to 1.2 final. This is the "Microsoft multipart mode", as natively sent by Outlook. It is known to work properly on Outlook, Outlook Express, Yahoo Mail, and to a large degree also on Mac Mail (with an additional attachment listed for an inline element, despite the inline element also shown inline). Does not work properly on Lotus Notes (attachments won't be shown there).

        See Also:
        Constant Field Values
      • MULTIPART_MODE_MIXED_RELATED

        public static final int MULTIPART_MODE_MIXED_RELATED
        Constant indicating a multipart message with a root multipart element "mixed" plus a nested multipart element of type "related". Texts and inline elements will get added to the nested "related" element, while attachments will get added to the "mixed" root element.

        This is the default since Spring 1.2.1. This is arguably the most correct MIME structure, according to the MIME spec: It is known to work properly on Outlook, Outlook Express, Yahoo Mail, and Lotus Notes. Does not work properly on Mac Mail. If you target Mac Mail or experience issues with specific mails on Outlook, consider using MULTIPART_MODE_RELATED instead.

        See Also:
        Constant Field Values