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 DataSources 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 Files is the file name itself and for URLs 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 Files and URLs. When embedding a
DataSource, the code uses the equals() method defined on the DataSources to make the determination.
- Since:
- 1.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intDefinition of the length of generated CID's. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoidBuilds the MimeMessage.Embeds the specifiedDataSourcein the HTML using a randomly generated Content-ID.Embeds the specifiedDataSourcein the HTML using the specified Content-ID.Embeds a file in the HTML.Embeds a file in the HTML.Parses the specifiedStringas a URL that will then be embedded in the message.Embeds an URL in the HTML.getHtml()Gets the HTML content.getText()Gets the message text.setHtmlMsg(String html) Sets the HTML content.Sets the message.setTextMsg(String text) Sets the text content.Methods inherited from class org.apache.commons.mail2.jakarta.MultiPartEmail
addPart, addPart, addPart, attach, attach, attach, attach, attach, attach, attach, createBodyPart, createMimeMultipart, getContainer, getPrimaryBodyPart, getSubType, init, isBoolHasAttachments, isInitialized, setBoolHasAttachments, setInitialized, setSubTypeMethods inherited from class org.apache.commons.mail2.jakarta.Email
addBcc, addBcc, addBcc, addBcc, addCc, addCc, addCc, addCc, addHeader, addReplyTo, addReplyTo, addReplyTo, addTo, addTo, addTo, addTo, createMimeMessage, getAuthenticator, getBccAddresses, getBounceAddress, getCcAddresses, getCharsetName, getContent, getContentType, getEmailBody, getFromAddress, getHeader, getHeaders, getHostName, getMailSession, getMessage, getMimeMessage, getPopHost, getPopPassword, getPopUserName, getReplyToAddresses, getSentDate, getSmtpPort, getSocketConnectionTimeout, getSocketTimeout, getSslSmtpPort, getSubject, getToAddresses, isDebug, isPopBeforeSmtp, isSendPartial, isSSLCheckServerIdentity, isSSLOnConnect, isStartTLSEnabled, isStartTLSRequired, send, sendMimeMessage, setAuthentication, setAuthenticator, setBcc, setBounceAddress, setCc, setCharset, setContent, setContent, setContent, setContentType, setDebug, setFrom, setFrom, setFrom, setFromAddress, setHeaders, setHostName, setMailSession, setMailSessionFromJNDI, setMessage, setPopBeforeSmtp, setPopBeforeSmtp, setPopHost, setPopPassword, setPopUsername, setReplyTo, setSendPartial, setSentDate, setSmtpPort, setSocketConnectionTimeout, setSocketTimeout, setSSLCheckServerIdentity, setSSLOnConnect, setSslSmtpPort, setStartTLSEnabled, setStartTLSRequired, setSubject, setTo, toInternetAddressArray, updateContentType
-
Field Details
-
CID_LENGTH
Definition of the length of generated CID's.- See Also:
-
-
Constructor Details
-
HtmlEmail
public HtmlEmail()Constructs a new instance.
-
-
Method Details
-
buildMimeMessage
Builds 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:
buildMimeMessagein classMultiPartEmail- Throws:
EmailException- if there was an error.- Since:
- 1.0
-
embed
Embeds the specifiedDataSourcein the HTML using a randomly generated Content-ID. Returns the generated Content-ID string.- Parameters:
dataSource- theDataSourceto embedname- the name that will be set in the file name header field- Returns:
- the generated Content-ID for this
DataSource - Throws:
EmailException- if the embedding fails or ifnameis null or empty- Since:
- 1.1
- See Also:
-
embed
public String embed(jakarta.activation.DataSource dataSource, String name, String cid) throws EmailException Embeds the specifiedDataSourcein the HTML using the specified Content-ID. Returns the specified Content-ID string.- Parameters:
dataSource- theDataSourceto embedname- the name that will be set in the file name 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 ifnameis null or empty- Since:
- 1.1
-
embed
Embeds a file in the HTML. This implementation delegates toembed(File, String).- Parameters:
file- TheFileobject to embed- Returns:
- A String with the Content-ID of the file.
- Throws:
EmailException- when the suppliedFilecannot be used; also seeMimeBodyPartfor 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:xxxxxxURL, 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
FileDataSourcetoembed(DataSource, String, String), this method attempts to validate the file before embedding it in the message and will throwEmailExceptionif the validation fails. In this case, theHtmlEmailobject will not be changed.- Parameters:
file- TheFileto embedcid- the Content-ID to use for the embeddedFile- Returns:
- A String with the Content-ID of the file.
- Throws:
EmailException- when the suppliedFilecannot be used or if the file has already been embedded; also seeMimeBodyPartfor definitions- Since:
- 1.1
-
embed
Parses the specifiedStringas 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 file name header field.- Returns:
- A String with the Content-ID of the URL.
- Throws:
EmailException- when URL supplied is invalid or ifnameis null or empty; also seeMimeBodyPartfor 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:xxxxxxURL, 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
URLDataSourcetoembed(DataSource, String, String), this method attempts to validate the URL before embedding it in the message and will throwEmailExceptionif the validation fails. In this case, theHtmlEmailobject 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 file name header field.- Returns:
- A String with the Content-ID of the file.
- Throws:
EmailException- when URL supplied is invalid or ifnameis null or empty; also seeMimeBodyPartfor definitions- Since:
- 1.0
-
getHtml
Gets the HTML content.- Returns:
- the HTML content.
- Since:
- 1.6.0
-
getText
Gets the message text.- Returns:
- the message text.
- Since:
- 1.6.0
-
setHtmlMsg
Sets the HTML content.- Parameters:
html- A String.- Returns:
- An HtmlEmail.
- Throws:
EmailException- see jakarta.mail.internet.MimeBodyPart for definitions- Since:
- 1.0
-
setMsg
Sets 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:
setMsgin classMultiPartEmail- Parameters:
msg- the message text to use- Returns:
- this
HtmlEmail - Throws:
EmailException- if msg is null or empty; see jakarta.mail.internet.MimeBodyPart for definitions- Since:
- 1.0
-
setTextMsg
Sets the text content.- Parameters:
text- A String.- Returns:
- An HtmlEmail.
- Throws:
EmailException- see jakarta.mail.internet.MimeBodyPart for definitions- Since:
- 1.0
-