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.
Email Processor
- 1. Scope
- 2. Data Input
- 3. Simple Messages
- 4. Character Encoding
- 5. Message Parts
- 6. Inline and Out of Line Parts
- 6.1. Inline Parts
- 6.2. Out of Line Parts
- 7. Properties
- 8. Examples
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/credentials/username | 0..1 | The SMTP username |
| 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=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-typeattribute, for exampletext/plain - Text content
For example:
<p:processor 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>
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
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/mixedcontent 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/alternativecontent 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/relatedcontent 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
bodyorpartelement. - 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 roothtmlelement must be present. -
Text type: this is the case when the content type starts with
text/, for exampletext/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"><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"><p:input name="data"><message>...</message></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"><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>
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"><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"/><p:input name="pdf-document"/></p:processor>