The examples/mail project contains an example of the email support in action. It demonstrates proper packaging, and it contains a number of example that demonstrate the key features currently supported.
You don't need to learn a whole new templating language to use Seam Mail—an email is just facelet!
<m:message xmlns="https://www.w3.org/1999/xhtml"
xmlns:m="https://jboss.com/products/seam/mail"
xmlns:h="https://java.sun.com/jsf/html">
<m:from name="Peter" address="[email protected]" />
<m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>
<m:subject>Try out Seam!</m:subject>
<m:body>
<p><h:outputText value="Dear #{person.firstname}" />,</p>
<p>You can try out Seam by visiting
<a href="https://labs.jboss.com/jbossseam">https://labs.jboss.com/jbossseam</a>.</p>
<p>Regards,</p>
<p>Peter</p>
</m:body>
</m:message>
The <m:message> tag wraps the whole message, and tells Seam to start rendering an email. Inside the <m:message> tag we use an <m:from> tag to set who the message is from, a <m:to> tag to specify a sender (notice how we use EL as we would in a normal facelet), and a <m:subject> tag.
The <m:body> tag wraps the body of the email. You can use regular HTML tags inside the body as well as JSF components.
So, now you have your email template, how do you go about sending it? Well, at the end of rendering the m:message the mailSession is called to send the email, so all you have to do is ask Seam to render the view:
@In(create=true)
private Renderer renderer;
public void send() {
try {
renderer.render("/simple.xhtml");
facesMessages.add("Email sent successfully");
}
catch (Exception e) {
facesMessages.add("Email sending failed: " + e.getMessage());
}
}
If, for example, you entered an invalid email address, then an exception would be thrown, which is caught and then displayed to the user.
Seam makes it easy to attach files to an email. It supports most of the standard java types used when working with files.
If you wanted to email the jboss-seam-mail.jar:
<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar"/>
Seam will load the file from the classpath, and attach it to the email. By default it would be attached as jboss-seam-mail.jar; if you wanted it to have another name you would just add the fileName attribute:
<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar" fileName="this-is-so-cool.jar"/>
You could also attach a java.io.File, a java.net.URL:
<m:attachment value="#{numbers}"/>
Or a byte[] or a java.io.InputStream:
<m:attachment value="#{person.photo}" contentType="image/png"/>
You'll notice that for a byte[] and a java.io.InputStream you need to specify the MIME type of the attachment (as that information is not carried as part of the file).
And it gets even better, you can attach a Seam generated PDF, or any standard JSF view, just by wrapping a <m:attachment> around the normal tags you would use:
<m:attachment fileName="tiny.pdf">
<p:document>
A very tiny PDF
</p:document>
</m:attachment>
If you had a set of files you wanted to attach (for example a set of pictures loaded from a database) you can just use a <ui:repeat>:
<ui:repeat value="#{people}" var="person">
<m:attachment value="#{person.photo}" contentType="image/jpeg"
fileName="#{person.firstname}_#{person.lastname}.jpg"/>
</ui:repeat>
16.1.2. HTML/Text alternative part
Whilst most mail readers nowadays support HTML, some don't, so you can add a plain text alternative to your email body:
<m:body>
<f:facet name="alternative">Sorry, your email reader can't show our fancy email,
please go to https://labs.jboss.com/jbossseam to explore Seam.</f:facet>
</m:body>
16.1.3. Multiple recipients
Often you'll want to send an email to a group of recipients (for example your users). All of the recipient mail tags can be placed inside a <ui:repeat>:
<ui:repeat value="#{allUsers} var="user">
<m:to name="#{user.firstname} #{user.lastname}" address="#{user.emailAddress}" />
</ui:repeat>
16.1.4. Multiple messages
Sometimes, however, you need to send a slightly different message to each recipient (e.g. a password reset). The best way to do this is to place the whole message inside a <ui:repeat>:
<ui:repeat value="#{people}" var="p">
<m:message>
<m:from name="#{person.firstname} #{person.lastname}">#{person.address}</m:from>
<m:to name="#{p.firstname}">#{p.address}</m:to>
...
</m:message>
</ui:repeat>
The mail templating example shows that facelets templating Just Works with the Seam mail tags.
Our template.xhtml contains:
<m:message>
<m:from name="Seam" address="[email protected]" />
<m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>
<m:subject>#{subject}</m:subject>
<m:body>
<html>
<body>
<ui:insert name="body">This is the default body, specified by the template.
</ui:insert>
</body>
</html>
</m:body>
</m:message>
Our templating.xhtml contains:
<ui:param name="subject" value="Templating with Seam Mail"/>
<ui:define name="body">
<p>This example demonstrates that you can easily use <i>facelets templating</i> in email!</p>
</ui:define>
16.1.6. Internationalisation
Seam supports sending internationalised messages. By default, the encoding provided by JSF is used, but this can be overridden on the template:
<m:message charset="UTF-8">
...
</m:message>
The body, subject and recipient (and from) name will be encoded. You'll need to make sure facelets uses the correct charset for parsing your pages by setting encoding of the template:
<?xml version="1.0" encoding="UTF-8"?>
Sometimes you'll want to add other headers to your email. Seam provides support for some (see
Section 16.4, “Tags”). For example, we can set the importance of the email, and ask for a read receipt:
<m:message xmlns:m="https://jboss.com/products/seam/mail"
importance="low"
requestReadReceipt="true"/>
Otherise you can add any header to the message using the <m:header> tag:
<m:header name="X-Sent-From" value="JBoss Seam"/>
