java.lang.Object | |
↳ | org.springframework.mail.javamail.MimeMessageHelper |
Helper class for populating a javax.mail.internet.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("me@mail.com"); message.setTo("you@mail.com"); 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.
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | MULTIPART_MODE_MIXED | Constant indicating a multipart message with a single root multipart element of type "mixed". | |||||||||
int | MULTIPART_MODE_MIXED_RELATED | Constant indicating a multipart message with a root multipart element "mixed" plus a nested multipart element of type "related". | |||||||||
int | MULTIPART_MODE_NO | Constant indicating a non-multipart message. | |||||||||
int | MULTIPART_MODE_RELATED | Constant indicating a multipart message with a single root multipart element of type "related". |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Create a new MimeMessageHelper for the given MimeMessage,
assuming a simple text message (no multipart content,
i.e.
| |||||||||||
Create a new MimeMessageHelper for the given MimeMessage,
assuming a simple text message (no multipart content,
i.e.
| |||||||||||
Create a new MimeMessageHelper for the given MimeMessage,
in multipart mode (supporting alternative texts, inline
elements and attachments) if requested.
| |||||||||||
Create a new MimeMessageHelper for the given MimeMessage,
in multipart mode (supporting alternative texts, inline
elements and attachments) if requested.
| |||||||||||
Create a new MimeMessageHelper for the given MimeMessage,
in multipart mode (supporting alternative texts, inline
elements and attachments) if requested.
| |||||||||||
Create a new MimeMessageHelper for the given MimeMessage,
in multipart mode (supporting alternative texts, inline
elements and attachments) if requested.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Add an attachment to the MimeMessage, taking the content from an
org.springframework.core.io.InputStreamResource . | |||||||||||
Add an attachment to the MimeMessage, taking the content from an
org.springframework.core.io.InputStreamResource . | |||||||||||
Add an attachment to the MimeMessage, taking the content from a
java.io.File . | |||||||||||
Add an attachment to the MimeMessage, taking the content from a
javax.activation.DataSource . | |||||||||||
Add an inline element to the MimeMessage, taking the content from an
org.springframework.core.InputStreamResource , and
specifying the content type explicitly. | |||||||||||
Add an inline element to the MimeMessage, taking the content from a
org.springframework.core.io.Resource . | |||||||||||
Add an inline element to the MimeMessage, taking the content from a
javax.activation.DataSource . | |||||||||||
Add an inline element to the MimeMessage, taking the content from a
java.io.File . | |||||||||||
Return the specific character encoding used for this message, if any.
| |||||||||||
Return the
FileTypeMap used by this MimeMessageHelper. | |||||||||||
Return the underlying MimeMessage object.
| |||||||||||
Return the underlying MIME "multipart/related" object, if any.
| |||||||||||
Return the root MIME "multipart/mixed" object, if any.
| |||||||||||
Return whether this helper is in multipart mode,
i.e.
| |||||||||||
Return whether this helper will validate all addresses passed to it.
| |||||||||||
Set the Java Activation Framework
FileTypeMap to use
for determining the content type of inline content and attachments
that get added to the message. | |||||||||||
Set the priority ("X-Priority" header) of the message.
| |||||||||||
Set the sent-date of the message.
| |||||||||||
Set the subject of the message, using the correct encoding.
| |||||||||||
Set the given text directly as content in non-multipart mode
or as default body part in multipart mode.
| |||||||||||
Set the given text directly as content in non-multipart mode
or as default body part in multipart mode.
| |||||||||||
Set the given plain text and HTML text as alternatives, offering
both options to the email client.
| |||||||||||
Set whether to validate all addresses which get passed to this helper.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Create an Activation Framework DataSource for the given InputStreamSource.
| |||||||||||
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.
| |||||||||||
Determine the default encoding for the given MimeMessage.
| |||||||||||
Determine the default Java Activation FileTypeMap for the given MimeMessage.
| |||||||||||
Set the given MimeMultipart objects for use by this MimeMessageHelper.
| |||||||||||
Validate the given mail address.
| |||||||||||
Validate all given mail addresses.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
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.
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.
Constant indicating a non-multipart message.
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).
Create a new MimeMessageHelper for the given MimeMessage, assuming a simple text message (no multipart content, i.e. no alternative texts and no inline elements or attachments).
The character encoding for the message will be taken from the passed-in MimeMessage object, if carried there. Else, JavaMail's default encoding will be used.
mimeMessage | MimeMessage to work on |
---|
setDefaultEncoding(String)
Create a new MimeMessageHelper for the given MimeMessage, assuming a simple text message (no multipart content, i.e. no alternative texts and no inline elements or attachments).
mimeMessage | MimeMessage to work on |
---|---|
encoding | the character encoding to use for the message |
Create a new MimeMessageHelper for the given MimeMessage, in multipart mode (supporting alternative texts, inline elements and attachments) if requested.
Consider using the MimeMessageHelper constructor that takes a multipartMode argument to choose a specific multipart mode other than MULTIPART_MODE_MIXED_RELATED.
The character encoding for the message will be taken from the passed-in MimeMessage object, if carried there. Else, JavaMail's default encoding will be used.
mimeMessage | MimeMessage to work on |
---|---|
multipart | whether to create a multipart message that supports alternative texts, inline elements and attachments (corresponds to MULTIPART_MODE_MIXED_RELATED) |
if multipart creation failed | |
MessagingException |
setDefaultEncoding(String)
Create a new MimeMessageHelper for the given MimeMessage, in multipart mode (supporting alternative texts, inline elements and attachments) if requested.
Consider using the MimeMessageHelper constructor that takes a multipartMode argument to choose a specific multipart mode other than MULTIPART_MODE_MIXED_RELATED.
mimeMessage | MimeMessage to work on |
---|---|
multipart | whether to create a multipart message that supports alternative texts, inline elements and attachments (corresponds to MULTIPART_MODE_MIXED_RELATED) |
encoding | the character encoding to use for the message |
if multipart creation failed | |
MessagingException |
Create a new MimeMessageHelper for the given MimeMessage, in multipart mode (supporting alternative texts, inline elements and attachments) if requested.
The character encoding for the message will be taken from the passed-in MimeMessage object, if carried there. Else, JavaMail's default encoding will be used.
mimeMessage | MimeMessage to work on |
---|---|
multipartMode | which kind of multipart message to create (MIXED, RELATED, MIXED_RELATED, or NO) |
if multipart creation failed | |
MessagingException |
MULTIPART_MODE_NO
MULTIPART_MODE_MIXED
MULTIPART_MODE_RELATED
MULTIPART_MODE_MIXED_RELATED
setDefaultEncoding(String)
Create a new MimeMessageHelper for the given MimeMessage, in multipart mode (supporting alternative texts, inline elements and attachments) if requested.
mimeMessage | MimeMessage to work on |
---|---|
multipartMode | which kind of multipart message to create (MIXED, RELATED, MIXED_RELATED, or NO) |
encoding | the character encoding to use for the message |
if multipart creation failed | |
MessagingException |
Add an attachment to the MimeMessage, taking the content from an
org.springframework.core.io.InputStreamResource
.
Note that the InputStream returned by the InputStreamSource
implementation needs to be a fresh one on each call, as
JavaMail will invoke getInputStream()
multiple times.
attachmentFilename | the name of the attachment as it will appear in the mail |
---|---|
inputStreamSource | the resource to take the content from (all of Spring's Resource implementations can be passed in here) |
contentType | the content type to use for the element |
in case of errors | |
MessagingException |
Add an attachment to the MimeMessage, taking the content from an
org.springframework.core.io.InputStreamResource
.
The content type will be determined by the given filename for the attachment. Thus, any content source will be fine, including temporary files with arbitrary filenames.
Note that the InputStream returned by the InputStreamSource
implementation needs to be a fresh one on each call, as
JavaMail will invoke getInputStream()
multiple times.
attachmentFilename | the name of the attachment as it will appear in the mail |
---|---|
inputStreamSource | the resource to take the content from (all of Spring's Resource implementations can be passed in here) |
in case of errors | |
MessagingException |
Add an attachment to the MimeMessage, taking the content from a
java.io.File
.
The content type will be determined by the name of the given content file. Do not use this for temporary files with arbitrary filenames (possibly ending in ".tmp" or the like)!
attachmentFilename | the name of the attachment as it will appear in the mail |
---|---|
file | the File resource to take the content from |
in case of errors | |
MessagingException |
Add an attachment to the MimeMessage, taking the content from a
javax.activation.DataSource
.
Note that the InputStream returned by the DataSource implementation
needs to be a fresh one on each call, as JavaMail will invoke
getInputStream()
multiple times.
attachmentFilename | the name of the attachment as it will appear in the mail (the content type will be determined by this) |
---|---|
dataSource | the javax.activation.DataSource to take
the content from, determining the InputStream and the content type |
in case of errors | |
MessagingException |
MessagingException | |
---|---|
UnsupportedEncodingException |
MessagingException |
---|
MessagingException | |
---|---|
UnsupportedEncodingException |
MessagingException |
---|
Add an inline element to the MimeMessage, taking the content from an
org.springframework.core.InputStreamResource
, and
specifying the content type explicitly.
You can determine the content type for any given filename via a Java Activation Framework's FileTypeMap, for example the one held by this helper.
Note that the InputStream returned by the InputStreamSource implementation
needs to be a fresh one on each call, as JavaMail will invoke
getInputStream()
multiple times.
NOTE: Invoke addInline
after setText
;
else, mail readers might not be able to resolve inline references correctly.
contentId | the content ID to use. Will end up as "Content-ID" header in the body part, surrounded by angle brackets: e.g. "myId" -> "<myId>". Can be referenced in HTML source via src="cid:myId" expressions. |
---|---|
inputStreamSource | the resource to take the content from |
contentType | the content type to use for the element |
in case of errors | |
MessagingException |
Add an inline element to the MimeMessage, taking the content from a
org.springframework.core.io.Resource
.
The content type will be determined by the name of the given content file. Do not use this for temporary files with arbitrary filenames (possibly ending in ".tmp" or the like)!
Note that the InputStream returned by the Resource implementation
needs to be a fresh one on each call, as JavaMail will invoke
getInputStream()
multiple times.
NOTE: Invoke addInline
after setText(String)
;
else, mail readers might not be able to resolve inline references correctly.
contentId | the content ID to use. Will end up as "Content-ID" header in the body part, surrounded by angle brackets: e.g. "myId" -> "<myId>". Can be referenced in HTML source via src="cid:myId" expressions. |
---|---|
resource | the resource to take the content from |
in case of errors | |
MessagingException |
Add an inline element to the MimeMessage, taking the content from a
javax.activation.DataSource
.
Note that the InputStream returned by the DataSource implementation
needs to be a fresh one on each call, as JavaMail will invoke
getInputStream()
multiple times.
NOTE: Invoke addInline
after setText(String)
;
else, mail readers might not be able to resolve inline references correctly.
contentId | the content ID to use. Will end up as "Content-ID" header in the body part, surrounded by angle brackets: e.g. "myId" -> "<myId>". Can be referenced in HTML source via src="cid:myId" expressions. |
---|---|
dataSource | the javax.activation.DataSource to take
the content from, determining the InputStream and the content type |
in case of errors | |
MessagingException |
Add an inline element to the MimeMessage, taking the content from a
java.io.File
.
The content type will be determined by the name of the given content file. Do not use this for temporary files with arbitrary filenames (possibly ending in ".tmp" or the like)!
NOTE: Invoke addInline
after setText(String)
;
else, mail readers might not be able to resolve inline references correctly.
contentId | the content ID to use. Will end up as "Content-ID" header in the body part, surrounded by angle brackets: e.g. "myId" -> "<myId>". Can be referenced in HTML source via src="cid:myId" expressions. |
---|---|
file | the File resource to take the content from |
in case of errors | |
MessagingException |
MessagingException |
---|
MessagingException | |
---|---|
UnsupportedEncodingException |
Return the FileTypeMap
used by this MimeMessageHelper.
Return the underlying MimeMessage object.
Return the underlying MIME "multipart/related" object, if any. Can be used to manually add body parts, inline elements, etc.
This will be nested within the root MimeMultipart, in case of a multipart mail.
IllegalStateException | if this helper is not in multipart mode |
---|
isMultipart()
getRootMimeMultipart()
Return the root MIME "multipart/mixed" object, if any. Can be used to manually add attachments.
This will be the direct content of the MimeMessage, in case of a multipart mail.
IllegalStateException | if this helper is not in multipart mode |
---|
isMultipart()
getMimeMessage()
Return whether this helper is in multipart mode, i.e. whether it holds a multipart message.
Return whether this helper will validate all addresses passed to it.
MessagingException |
---|
MessagingException |
---|
MessagingException |
---|
MessagingException |
---|
Set the Java Activation Framework FileTypeMap
to use
for determining the content type of inline content and attachments
that get added to the message.
Default is the FileTypeMap
that the underlying
MimeMessage carries, if any, or the Activation Framework's default
FileTypeMap
instance else.
addInline(String, File)
addAttachment(String, File)
setDefaultFileTypeMap(FileTypeMap)
getDefaultFileTypeMap()
ConfigurableMimeFileTypeMap
MessagingException |
---|
MessagingException | |
---|---|
UnsupportedEncodingException |
Set the priority ("X-Priority" header) of the message.
priority | the priority value; typically between 1 (highest) and 5 (lowest) |
---|
in case of errors | |
MessagingException |
MessagingException |
---|
MessagingException | |
---|---|
UnsupportedEncodingException |
Set the sent-date of the message.
sentDate | the date to set (never null ) |
---|
in case of errors | |
MessagingException |
Set the subject of the message, using the correct encoding.
subject | the subject text |
---|
in case of errors | |
MessagingException |
Set the given text directly as content in non-multipart mode or as default body part in multipart mode. Always applies the default content type "text/plain".
NOTE: Invoke addInline(String, File)
after setText
;
else, mail readers might not be able to resolve inline references correctly.
text | the text for the message |
---|
in case of errors | |
MessagingException |
Set the given text directly as content in non-multipart mode or as default body part in multipart mode. The "html" flag determines the content type to apply.
NOTE: Invoke addInline(String, File)
after setText
;
else, mail readers might not be able to resolve inline references correctly.
text | the text for the message |
---|---|
html | whether to apply content type "text/html" for an HTML mail, using default content type ("text/plain") else |
in case of errors | |
MessagingException |
Set the given plain text and HTML text as alternatives, offering both options to the email client. Requires multipart mode.
NOTE: Invoke addInline(String, File)
after setText
;
else, mail readers might not be able to resolve inline references correctly.
plainText | the plain text for the message |
---|---|
htmlText | the HTML text for the message |
in case of errors | |
MessagingException |
MessagingException |
---|
MessagingException |
---|
Set whether to validate all addresses which get passed to this helper. Default is "false".
Note that this is by default just available for JavaMail >= 1.3.
You can override the default validateAddress method
for
validation on older JavaMail versions (or for custom validation).
Create an Activation Framework DataSource for the given InputStreamSource.
inputStreamSource | the InputStreamSource (typically a Spring Resource) |
---|---|
contentType | the content type |
name | the name of the DataSource |
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.
Texts and inline elements can either be stored in the root element itself (MULTIPART_MODE_MIXED, MULTIPART_MODE_RELATED) or in a nested element rather than the root element directly (MULTIPART_MODE_MIXED_RELATED).
By default, the root MimeMultipart element will be of type "mixed" (MULTIPART_MODE_MIXED) or "related" (MULTIPART_MODE_RELATED). The main multipart element will either be added as nested element of type "related" (MULTIPART_MODE_MIXED_RELATED) or be identical to the root element itself (MULTIPART_MODE_MIXED, MULTIPART_MODE_RELATED).
mimeMessage | the MimeMessage object to add the root MimeMultipart object to |
---|---|
multipartMode | the multipart mode, as passed into the constructor (MIXED, RELATED, MIXED_RELATED, or NO) |
if multipart creation failed | |
MessagingException |
Determine the default encoding for the given MimeMessage.
mimeMessage | the passed-in MimeMessage |
---|
null
if none found
Determine the default Java Activation FileTypeMap for the given MimeMessage.
mimeMessage | the passed-in MimeMessage |
---|
Set the given MimeMultipart objects for use by this MimeMessageHelper.
root | the root MimeMultipart object, which attachments will be added to;
or null to indicate no multipart at all |
---|---|
main | the main MimeMultipart object, which text(s) and inline elements will be added to (can be the same as the root multipart object, or an element nested underneath the root multipart element) |
Validate the given mail address. Called by all of MimeMessageHelper's address setters and adders.
Default implementation invokes InternetAddress.validate()
,
provided that address validation is activated for the helper instance.
Note that this method will just work on JavaMail >= 1.3. You can override it for validation on older JavaMail versions or for custom validation.
address | the address to validate |
---|
if validation failed | |
AddressException |
isValidateAddresses()
Validate all given mail addresses. Default implementation simply delegates to validateAddress for each address.
addresses | the addresses to validate |
---|
if validation failed | |
AddressException |