Email Processor
1. Scope
The Email processor can send emails through an SMTP server (the usual way of
sending emails). Its input contains the basic configuration (SMTP host, subject,
etc.) as well as inline message body content. Alternatively, the message content can
refer to external resources, such as resources on disk or dynamically generated
content. It features the following high-level functionality:
-
Multiple recipients: send the same email to multiple recipients.
-
Multipart hierarchy: it is possible to have multiple levels of multipart
messages.
-
Binary attachments: binary files such as images and PDF files can be
attached to an email.
-
Dynamic attachments: attachments can be generated dynamically. It is for
example possible to attach a dynamically generated chart or PDF file.
2. Data Input
The data input contains the configuration of the processor as well
as the message header and body. The following table describes the configuration
elements:
Name |
Cardinality |
Description |
message |
1 |
Root element |
message/smtp-host |
0..1 |
The SMTP host used to send the message |
message/from |
1 |
Sender of the message. Contains an email element and an optional name element.
|
message/to |
1..n |
Recipient(s) of the message. Contains an email element and an optional name element.
|
message/cc |
0..n |
Carbon copy recipient(s) of the message. Contains an email element and an optional name element.
|
message/bcc |
0..n |
Blind carbon copy recipient(s) of the message. Contains an email element and an optional name element.
|
message/subject |
1 |
Subject of the message |
message/body |
1 |
Indicates a message body optionally containing multiple parts |
message/body/@content-type |
1 |
The content-type of this body part. This attribute can also include a
charset attribute to specify a character encoding for text
types. For example: text/plain; charset=utf-8. This
attribute may also specify a multipart data type:
multipart/mixed, multipart/alternative or
multipart/related.
|
message/body/part |
0..n |
A message body part, if the body element specifies a multipart
content-type attribute.
|
message/body/part/@name |
1 |
The name of this body part |
message/body/part@/content-type |
1 |
The content-type of this body part. This can also include a
charset attribute to specify a character encoding for text
types. For example: text/plain; charset=utf-8. This
attribute may also specify a multipart data type:
multipart/mixed, multipart/alternative or
multipart/related. In this case, the part contains an
embedded multipart message. This replaces the depreated
mime-multipart attribute.
|
message/body/part@/content-disposition |
0..1 |
The optional Content-Disposition header of this body part. Not allowed
if the part contains embedded parts.
|
message/body/part@/content-id |
0..1 |
The optional Content-ID header of this body part.
|
message/body/part/* |
1 |
The content of the body part. This can contain embedded
part elements if the content is multipart. It can be XHTML
if the content-type is text/html. Finally, it can be any
text content, including just plain HTML (which can be embedded in a
CDATA section for convenience).
|
3. Simple Messages
A simple message requires a body element with:
- A text content-type attribute, for example text/plain
- Text content
For example:
<p:processor name="oxf:email" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="data"> <message> <smtp-host>mail.example.org</smtp-host>
<from> <email>trove@smith.com</email>
<name>Trove Smith</name>
</from> <to> <email>jani@smith.com</email>
<name>Jani Smith</name>
</to> <subject>Reminder</subject>
<body content-type="text/plain">Hello, Jani!
</body> </message> </p:input> </p:processor>
4. Character Encoding
In the example above, no character encoding is specified for the
body element. This determines what character encoding is used in
the body of the email message constructed by the Email processor. If no
encoding is specified, the default iso-8859-1 is used. In some
cases, it is useful to specify a character encoding. For example, if it is known
that the message only contains ASCII characters, the us-ascii
encoding can be specified. If, on the other hand, the message contains
characters from multiple languages, the utf-8 encoding can be
specified.
Use the content-type attribute to specify an encoding, for
example: content-type="text/plain; charset=utf-8".
Note
XML itself support Unicode, in other words it is designed to allow representing
all the characters specified by the Unicode specification. Those characters can
all be represented with the UTF-8 encoding. Because of this, the Email
processor could always encode text using the UTF-8 encoding. However, some mail
clients may not all support that encoding. It is therefore left to the user of
the Email processor to specify the appropriate encoding.
5. Message Parts
An email message can be composed of several parts. Parts can be used for:
-
Attachments: for example, a simple text message may have one of more
image attachments. Usually, the multipart/mixed content type
is used for this purpose.
-
Alternative Formats: for example, both a plain text and an HTML
version of a same message may be sent. The recipient, or her mail software,
can then choose the most appropriate format to display. The
multipart/alternative content type is used for this purpose.
-
Dependencies: for example, an HTML message may refer to images or
other resources embedded in the same email. The
multipart/related content type is used for this purpose.
To create a multipart email, specify one of the multipart content types on the
body element. The body element must contain one or
more part elements.
In turn, part elements may contain other parts. In that case, a
part element must declare a multipart content type attribute, and
contain at least one part element.
The main part of the body is encapsulated by the body element of
the message.
6. Inline and Out of Line Parts
The content of a part can be specified in two ways:
-
Inline: the content is directly embedded in the body or
part element.
-
Out of line: the content is available from a resource or dynamically
generated.
6.1 Inline Parts
The content of the body or part element can be of
the following types:
-
HTML: the content type is text/html. In this case,
the inline content is considered as HTML and converted to HTML. A root
html element must be present.
-
Text type: this is the case when the content type starts with
text/, for example text/plain. In thise case,
a character encoding can be specified as well.
-
Binary Type: for all other content types, the body of the part
must contain Base64-encoded binary data.
6.2 Out of Line Parts
This mode is enabled when the part element contains an
src attribute.
You can refer to a part content using a regular URI, for example:
<part src="oxf:/image.jpg" content-type="image/jpeg"/>
You can also refer to dynamically generated content by referring to optional processor inputs. For
example:
<part src="input:image-content" content-type="image/jpeg"/>
In this case, the content of the image is obtained by reading the
image-content input of the Email processor. You can choose an
arbitray name for the input, as long as it is not data. Then,
connect a processor to the input, for example:
<p:processor name="oxf:url-generator" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="config"> <config> <url>oxf:/image.jpg</url>
<content-type>image/jpeg</content-type>
</config> </p:input> <p:output name="data" id="file"/>
</p:processor> <p:processor name="oxf:email" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="data"> </p:input> <p:input name="image-content" href="#file"/>
</p:processor>
When the content type of the input read is text (starts with
text/) or XML (text/xml,
application/xml, or ends with +xml), the input
document is expected to be in the text format specified by the text document format. When the
content type of the input read is binary (all the other cases), the input
document is expected to be in the binary format specified by the binary document format.
7. Properties
Several global properties are relevant to the Email processor. Refer to the Properties section for more
information.
8. Examples
8.1 Sending Alternative Parts
This example shows how to send both a text and HTML version of a message to
two recipients.
<p:processor name="oxf:email" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="data"> <message> <smtp-host>mail.company.com</smtp-host>
<from> <email>trove@smith.com</email>
<name>Trove Smith</name>
</from> <to> <email>jani@smith.com</email>
<name>Jani Smith</name>
</to> <to> <email>tori@smith.com</email>
<name>Tori Smith</name>
</to> <subject>Reminder</subject>
<body mime-multipart="alternative"> <part name="part1" content-type="text/plain">This is part 1
</part> <part name="part2" content-type="text/html"> </part> </body> </message> </p:input> </p:processor>
8.2 Related Parts and Attachments
This example shows how to send related parts with HTML, as well as
dynamically generated attachements.
<p:processor name="oxf:email" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="data"> <message> <smtp-host>mail.company.com</smtp-host>
<from> <email>trove@smith.com</email>
<name>Trove Smith</name>
</from> <to> <email>jani@smith.com</email>
<name>Jani Smith</name>
</to> <subject>Email Example</subject>
<body mime-multipart="alternative"> <!-- Provide simple text alternative -->
<part name="text" content-type="text/plain">This is some important message body.</part>
<!-- HTML alternative -->
<part name="html" content-type="multipart/related"> <part name="main" content-type="text/html"> <html> <head> <title>Email Example</title>
</head> <body> <p style="border: dotted 1px gray; padding: 5px">This is some<em>important</em>message body.
</p> <p>This is a static image attached to the email and referred to by the HTML version:
</p> <div style="border: dotted 1px gray; padding: 5px"> </div> <p>This is an dynamic chart image attached to the email and referred to by the HTML version:
</p> <div style="border: dotted 1px gray; padding: 5px"> </div> </body> </html> </part> <!-- Attachments -->
<part name="image" content-type="image/gif" content-disposition="inline; filename="logo.gif"" content-id="id1" src="oxf:/logo.gif"/>
<part name="chart" content-type="image/png" content-disposition="inline; filename="chart.png"" content-id="id2" src="input:png-document"/>
<part name="pdf" content-type="application/pdf" content-disposition="inline; filename="report.pdf"" src="input:pdf-document"/>
</part> </body> </message> </p:input> <p:input name="png-document"/>
<p:input name="pdf-document"/>
</p:processor>