Class HtmlEmail
- Direct Known Subclasses:
ImageHtmlEmail
This class is used to send HTML formatted email. A text message can also be set for HTML unaware email clients, such as text-based email clients.
This class also inherits from MultiPartEmail
, so it is easy to
add attachments to the email.
To send an email in HTML, one should create a HtmlEmail
, then
use the Email.setFrom(String)
, Email.addTo(String)
etc. methods.
The HTML content can be set with the setHtmlMsg(String)
method. The
alternative text content can be set with setTextMsg(String)
.
Either the text or HTML can be omitted, in which case the "main"
part of the multipart becomes whichever is supplied rather than a
multipart/alternative
.
Embedding Images and Media
It is also possible to embed URLs, files, or arbitrary
DataSource
s directly into the body of the mail:
HtmlEmail he = new HtmlEmail(); File img = new File("my/image.gif"); PNGDataSource png = new PNGDataSource(decodedPNGOutputStream); // a custom class StringBuffer msg = new StringBuffer(); msg.append("<html><body>"); msg.append("<img src=cid:").append(he.embed(img)).append(">"); msg.append("<img src=cid:").append(he.embed(png)).append(">"); msg.append("</body></html>"); he.setHtmlMsg(msg.toString()); // code to set the other email fields (not shown)
Embedded entities are tracked by their name, which for File
s is
the filename itself and for URL
s is the canonical path. It is
an error to bind the same name to more than one entity, and this class will
attempt to validate that for File
s and URL
s. When
embedding a DataSource
, the code uses the equals()
method defined on the DataSource
s to make the determination.
- Since:
- 1.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Definition of the length of generated CID's.protected String
Html part of the message.Embedded images Map<String, InlineImage> where the key is the user-defined image name.protected List
<org.apache.commons.mail.HtmlEmail.InlineImage> Deprecated.As of commons-email 1.1, no longer used.protected String
Text part of the message.Fields inherited from class org.apache.commons.mail.Email
ATTACHMENTS, authenticator, bccList, bounceAddress, ccList, charset, content, CONTENT_TYPE, contentType, debug, EMAIL_BODY, EMAIL_SUBJECT, emailBody, FILE_SERVER, fromAddress, headers, hostName, ISO_8859_1, KOI8_R, MAIL_DEBUG, MAIL_HOST, MAIL_PORT, MAIL_SMTP_AUTH, MAIL_SMTP_CONNECTIONTIMEOUT, MAIL_SMTP_FROM, MAIL_SMTP_PASSWORD, MAIL_SMTP_SOCKET_FACTORY_CLASS, MAIL_SMTP_SOCKET_FACTORY_FALLBACK, MAIL_SMTP_SOCKET_FACTORY_PORT, MAIL_SMTP_TIMEOUT, MAIL_SMTP_USER, MAIL_TRANSPORT_PROTOCOL, MAIL_TRANSPORT_TLS, message, popBeforeSmtp, popHost, popPassword, popUsername, RECEIVER_EMAIL, RECEIVER_NAME, replyList, SENDER_EMAIL, SENDER_NAME, sentDate, SMTP, smtpPort, socketConnectionTimeout, socketTimeout, ssl, sslSmtpPort, subject, TEXT_HTML, TEXT_PLAIN, tls, toList, US_ASCII
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
Does the work of actually building the MimeMessage.Embeds a file in the HTML.Embeds a file in the HTML.Attempts to parse the specifiedString
as a URL that will then be embedded in the message.Embeds an URL in the HTML.embed
(DataSource dataSource, String name) Embeds the specifiedDataSource
in the HTML using a randomly generated Content-ID.embed
(DataSource dataSource, String name, String cid) Embeds the specifiedDataSource
in the HTML using the specified Content-ID.setHtmlMsg
(String aHtml) Set the HTML content.Set the message.setTextMsg
(String aText) Set the text content.Methods inherited from class org.apache.commons.mail.MultiPartEmail
addPart, addPart, addPart, attach, attach, attach, attach, attach, attach, createBodyPart, createMimeMultipart, getContainer, getPrimaryBodyPart, getSubType, init, isBoolHasAttachments, isInitialized, setBoolHasAttachments, setInitialized, setSubType
Methods inherited from class org.apache.commons.mail.Email
addBcc, addBcc, addBcc, addBcc, addCc, addCc, addCc, addCc, addHeader, addReplyTo, addReplyTo, addReplyTo, addTo, addTo, addTo, addTo, createMimeMessage, getBccAddresses, getBounceAddress, getCcAddresses, getFromAddress, getHeader, getHeaders, getHostName, getMailSession, getMimeMessage, getReplyToAddresses, getSentDate, getSmtpPort, getSocketConnectionTimeout, getSocketTimeout, getSslSmtpPort, getSubject, getToAddresses, isSendPartial, isSSL, isSSLCheckServerIdentity, isSSLOnConnect, isStartTLSEnabled, isStartTLSRequired, isTLS, send, sendMimeMessage, setAuthentication, setAuthenticator, setBcc, setBounceAddress, setCc, setCharset, setContent, setContent, setDebug, setFrom, setFrom, setFrom, setHeaders, setHostName, setMailSession, setMailSessionFromJNDI, setPopBeforeSmtp, setReplyTo, setSendPartial, setSentDate, setSmtpPort, setSocketConnectionTimeout, setSocketTimeout, setSSL, setSSLCheckServerIdentity, setSSLOnConnect, setSslSmtpPort, setStartTLSEnabled, setStartTLSRequired, setSubject, setTLS, setTo, toInternetAddressArray, updateContentType
-
Field Details
-
CID_LENGTH
Definition of the length of generated CID's.- See Also:
-
text
Text part of the message. This will be used as alternative text if the email client does not support HTML messages. -
html
Html part of the message. -
inlineImages
Deprecated.As of commons-email 1.1, no longer used. Inline embedded objects are now stored ininlineEmbeds
. -
inlineEmbeds
Embedded images Map<String, InlineImage> where the key is the user-defined image name.
-
-
Constructor Details
-
HtmlEmail
public HtmlEmail()
-
-
Method Details
-
setTextMsg
Set the text content.- Parameters:
aText
- A String.- Returns:
- An HtmlEmail.
- Throws:
EmailException
- see javax.mail.internet.MimeBodyPart for definitions- Since:
- 1.0
-
setHtmlMsg
Set the HTML content.- Parameters:
aHtml
- A String.- Returns:
- An HtmlEmail.
- Throws:
EmailException
- see javax.mail.internet.MimeBodyPart for definitions- Since:
- 1.0
-
setMsg
Set the message.This method overrides
MultiPartEmail.setMsg(String)
in order to send an HTML message instead of a plain text message in the mail body. The message is formatted in HTML for the HTML part of the message; it is left as is in the alternate text part.- Overrides:
setMsg
in classMultiPartEmail
- Parameters:
msg
- the message text to use- Returns:
- this
HtmlEmail
- Throws:
EmailException
- if msg is null or empty; see javax.mail.internet.MimeBodyPart for definitions- Since:
- 1.0
-
embed
Attempts to parse the specifiedString
as a URL that will then be embedded in the message.- Parameters:
urlString
- String representation of the URL.name
- The name that will be set in the filename header field.- Returns:
- A String with the Content-ID of the URL.
- Throws:
EmailException
- when URL supplied is invalid or ifname
is null or empty; also seeMimeBodyPart
for definitions- Since:
- 1.1
- See Also:
-
embed
Embeds an URL in the HTML.This method embeds a file located by an URL into the mail body. It allows, for instance, to add inline images to the email. Inline files may be referenced with a
cid:xxxxxx
URL, where xxxxxx is the Content-ID returned by the embed function. It is an error to bind the same name to more than one URL; if the same URL is embedded multiple times, the same Content-ID is guaranteed to be returned.While functionally the same as passing
URLDataSource
toembed(DataSource, String, String)
, this method attempts to validate the URL before embedding it in the message and will throwEmailException
if the validation fails. In this case, theHtmlEmail
object will not be changed.NOTE: Clients should take care to ensure that different URLs are bound to different names. This implementation tries to detect this and throw
EmailException
. However, it is not guaranteed to catch all cases, especially when the URL refers to a remote HTTP host that may be part of a virtual host cluster.- Parameters:
url
- The URL of the file.name
- The name that will be set in the filename header field.- Returns:
- A String with the Content-ID of the file.
- Throws:
EmailException
- when URL supplied is invalid or ifname
is null or empty; also seeMimeBodyPart
for definitions- Since:
- 1.0
-
embed
Embeds a file in the HTML. This implementation delegates toembed(File, String)
.- Parameters:
file
- TheFile
object to embed- Returns:
- A String with the Content-ID of the file.
- Throws:
EmailException
- when the suppliedFile
cannot be used; also seeMimeBodyPart
for definitions- Since:
- 1.1
- See Also:
-
embed
Embeds a file in the HTML.This method embeds a file located by an URL into the mail body. It allows, for instance, to add inline images to the email. Inline files may be referenced with a
cid:xxxxxx
URL, where xxxxxx is the Content-ID returned by the embed function. Files are bound to their names, which is the value returned byFile.getName()
. If the same file is embedded multiple times, the same CID is guaranteed to be returned.While functionally the same as passing
FileDataSource
toembed(DataSource, String, String)
, this method attempts to validate the file before embedding it in the message and will throwEmailException
if the validation fails. In this case, theHtmlEmail
object will not be changed.- Parameters:
file
- TheFile
to embedcid
- the Content-ID to use for the embeddedFile
- Returns:
- A String with the Content-ID of the file.
- Throws:
EmailException
- when the suppliedFile
cannot be used or if the file has already been embedded; also seeMimeBodyPart
for definitions- Since:
- 1.1
-
embed
Embeds the specifiedDataSource
in the HTML using a randomly generated Content-ID. Returns the generated Content-ID string.- Parameters:
dataSource
- theDataSource
to embedname
- the name that will be set in the filename header field- Returns:
- the generated Content-ID for this
DataSource
- Throws:
EmailException
- if the embedding fails or ifname
is null or empty- Since:
- 1.1
- See Also:
-
embed
Embeds the specifiedDataSource
in the HTML using the specified Content-ID. Returns the specified Content-ID string.- Parameters:
dataSource
- theDataSource
to embedname
- the name that will be set in the filename header fieldcid
- the Content-ID to use for thisDataSource
- Returns:
- the URL encoded Content-ID for this
DataSource
- Throws:
EmailException
- if the embedding fails or ifname
is null or empty- Since:
- 1.1
-
buildMimeMessage
Does the work of actually building the MimeMessage. Please note that a user rarely calls this method directly and only if he/she is interested in the sending the underlying MimeMessage without commons-email.- Overrides:
buildMimeMessage
in classMultiPartEmail
- Throws:
EmailException
- if there was an error.- Since:
- 1.0
-