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.
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 |
[SINCE 2012-07-23]
message/smtp-port | 0..1 | Override the default SMTP port used to send the message. Defaults are:
- plain SMTP: 25
- TLS: 587
- SSL: 465
|
[SINCE 2012-07-23]
message/encryption | 0..1 | - if blank, no encryption (plain SMTP) is used
tls: use TLSssl: use SSL
|
| message/credentials/username |
0..1 |
The SMTP username (required if TLS or SSL is used, optional otherwise) |
| message/credentials/password |
0..1 |
The SMTP password |
| 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/header |
0..n |
Optional extra email header to add. Contains a <name> element
and a <value> element.
|
| 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=us-ascii. 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).
|
When specifying email addresses, and when the <name> element is omitted, the
<email> element may contain several email addresses separated by commas:
<to xmlns:p="http://www.orbeon.com/oxf/pipeline">
<email>"Info" <info@orbeon.com>, "John" <john@example.org></email>
</to>
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 xmlns:p="http://www.orbeon.com/oxf/pipeline" name="oxf:email">
<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>
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 utf-8 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.
Use the content-type attribute to specify an encoding, for example:
content-type="text/plain; charset=us-ascii".
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. Note that 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.
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.
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.
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.
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 xmlns:p="http://www.orbeon.com/oxf/pipeline" 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 xmlns:p="http://www.orbeon.com/oxf/pipeline" 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 or config. Then, connect a processor to the input, for example:
<p:processor xmlns:p="http://www.orbeon.com/oxf/pipeline" name="oxf:url-generator">
<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 xmlns:p="http://www.orbeon.com/oxf/pipeline" name="oxf:email">
<p:input name="data">
<message>
...
</message>
</p:input>
<p:input name="image-content" href="#file"/>
</p:processor>
The custom input must be as specified by the text
document format or binary document format. The
content-type specified on the <part> element is then used to decode the
data and attach it to the email.
Note that some combinations might produce errors, for example providing a JPEG image on the input
and specifying a text/plain content type on the <part> element. You
must ensure that the content type specified to the mail processor is appropriate for the attachment
provided.
Properties
Several global properties are relevant to the Email processor. Refer to the Properties section below for more information.
Examples
Sending alternative parts
This example shows how to send both a text and HTML version of a message to
two recipients.
<p:processor xmlns:p="http://www.orbeon.com/oxf/pipeline" name="oxf:email">
<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">
<html>
<body>
<p>
This is part 2
</p>
</body>
</html>
</part>
</body>
</message>
</p:input>
</p:processor>
Related parts and attachments
This example shows how to send related parts with HTML, as well as dynamically generated
attachements.
<p:processor xmlns:p="http://www.orbeon.com/oxf/pipeline" name="oxf:email">
<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">
<img src="cid:id1"/>
</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">
<img src="cid:id2"/>
</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" href="#my-png"/>
<p:input name="pdf-document" href="#my-pdf"/>
</p:processor>
.
