EmailOutput node

Use the EmailOutput node to send email messages to one or more recipients.

This topic contains the following sections:

Purpose

The EmailOutput node delivers an email message from a message flow to an SMTP server that you specify.

You can configure the EmailOutput node by using the node properties in the IBM App Connect Enterprise Toolkit, or dynamically from the local environment and email output header (EmailOutputHeader) that are associated with the message (for more information, see Producing dynamic email messages). You can configure the EmailOutput node to produce an e-mail with a single attachment. When you produce email messages dynamically, you can specify multiple attachments.

The EmailOutput node is contained in the Email drawer of the message flow node palette, and is represented in the IBM App Connect Enterprise Toolkit by the following icon:

EmailOutput node icon

Configuring the EmailOutput node

When you have put an instance of the EmailOutput node into a message flow, you can configure it. For more information, see Configuring a message flow node. The properties of the node are displayed in the Properties view.

All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

The following is a description of the four levels of configuration of the EmailOutput node:
  • Option 1: Configure the EmailOutput node by using the node properties in the IBM App Connect Enterprise Toolkit to send an email with a statically-defined subject and text to a statically-defined list of recipients. The same email is sent to the same recipients and it has no attachments. This method is useful when you want to test the EmailOutput node, or when notification alone is sufficient. For more details, see Sending an email.
  • Option 2: This option is the same as Option 1 but with the inclusion of an attachment. This option causes the email message to be constructed as a MIME message. The subject, text, and list of recipients remains static, but the content of the attachment is sought dynamically from the message that is passed to the EmailOutput node at run time. The location of the attachment in the message is defined statically. For more details, see Sending an email with an attachment.
  • Option 3: This option allows for those properties in Options 1 and 2 to be optional, and to be overridden at run time by values that are specified in the local environment, the email output header (EmailOutputHeader), or the body of the message. This option allows a dynamic email message to be produced where the SMTP server, list of recipients, subject, text, and multiple attachments are all determined at run time. This option requires previous nodes in the message flow to construct these overrides. Where a text value is not specified in the node properties for the main body of the email, the body of the message that is passed to the EmailOutput node is used. However, content that you set in the Email message text property overrides dynamically-generated text in the message body. For more details, see Producing dynamic email messages.
  • Option 4: This option passes a MIME message to the EmailOutput node. The EmailOutput node uses the MIME parser to write the MIME message to a bit stream. This message is then sent to the list of recipients in the SMTP header. Local environment overrides are not taken into consideration when a MIME message is passed. For more details, see Sending a MIME message.

Email output header

The email output header (EmailOutputHeader) is a child of root. Values that you specify in this header override equivalent properties that you set on the node. Use the SMTP output header to specify any of the email attributes, such as its recipients.
Location Description
Root.EmailOutputHeader.To A comma separated list of email addresses.
Root.EmailOutputHeader.Cc A comma separated list of email addresses.
Root.EmailOutputHeader.Bcc A comma separated list of email addresses.
Root.EmailOutputHeader.From A comma separated list of email addresses.
Root.EmailOutputHeader.Reply-To A comma separated list of email addresses.
Root.EmailOutputHeader.Subject The subject of the email.
Root.EmailOutputHeader.Sender A single email address. This header is mandatory if multiple email addresses are specified in the Root.EmailOutputHeader.From field.

Any other children of the Root.EmailOutputHeader element are treated as custom headers and are also added to the outgoing email.

Local environment

Use the local environment to specify overrides to the SMTP server connection information and attachments.
Local environment Description
Destination.Email.SMTPServer The Server:Port of the SMTP server. Port is optional; if you do not specify it, the default value is 25.
Destination.Email.SecurityIdentity The security identity for authentication with the SMTP server, which can be the name of the userid and password pair that is defined using the mqsisetdbparms command, or it can reference an external resource that has a securityIdentity attribute that references a userid and password that are defined using the mqsisetdbparms command. In both cases, the value is appended after the string "smtp::". For example, if you use the mqsisetdbparms command to create a userid and password of smtp::myUseridPassword, the securityIdentity that is specified on the node, or indirectly in an external resource, is myUseridPassword.
Destination.Email.BodyContentType Identifies that the body of the email message contains HTML rather than plain text. You can set this property to text/plain, text/html, or text/xml; text/plain is the default value.
To set the content type for the body of the message, use the following notation. 
SET OutputLocalEnvironment.Destination.Email.BodyContentType = 
"text/html"
To additionally set the character set (charset) in which the message body is sent, use the following notation. 
SET OutputLocalEnvironment.Destination.Email.BodyContentType = 
"text/html; charset=utf-8"
This example sends a text/HTML email with a charset of UTF-8.
Destination.Email.MultiPartContentType The type of multipart, including related, mixed, and alternative. You can set any value here.
Destination.Email.Attachment.Content Either the attachment (BLOB/text), or an XPath or ESQL expression that references an element; for example, an element in the message tree or local environment. The value of the referenced element is taken as the content of the attachment.
  • If the element is a BLOB, it is an attachment.
  • If the element is text, check to see if it can be resolved to another element in the message tree or local environment. If it can be resolved, use that element. If it cannot be resolved, add this element as the attachment.
Destination.Email.Attachment.ContentType The type of attachment (also known as Internet Media Type), including text/plain, text/html, and text/xml. You can set any value here.
Destination.Email.Attachment.ContentName The name of the attachment.
Destination.Email.Attachment.ContentEncoding The encoding of the attachment: 7bit, base64, or quoted-printable.
  • 7bit is the default value that is used for ASCII text.
  • Base64 is used for non ASCII, whether non English or binary data. This format can be difficult to read.
  • Quoted-printable is an alternative to Base64, and is appropriate when the majority of the data is ASCII with some non-ASCII parts. This format is more readable; it provides a more compact encoding because the ASCII parts are not encoded.

Connecting the terminals

Connect the In terminal to the node from which outbound messages bound are routed.

Connect the Out or Failure terminal of this node to another node in this message flow to process the message further, process errors, or send the message to an additional destination.

If you connect one of these output terminals to another node in the message flow, the local environment that is associated with the message is enhanced with the following information for each destination to which the message has been put by this node:
Location Description
WrittenDestination.Email.smtpServer The Server:Port of the SMTP server.
WrittenDestination.Email.messageId The ID of the email sent message.

These values are written in WrittenDestination within the local environment tree structure.

If you do not connect either terminal, the local environment tree is unchanged.

Terminals and properties

The EmailOutput node terminals are described in the following table.

Terminal Description
In The input terminal that accepts a message for processing by the node.
Failure The output terminal to which the message is routed if a failure is detected when a message is propagated. Connect the Failure terminal of this node to another node in the message flow to process errors.
Out The output terminal to which the message is routed if it has been propagated successfully. Connect the Out terminal of this node to another node in the message flow to process the message further or send the message to an additional destination.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file at deployment).

The EmailOutput node Description properties are described in the following table.

Property M C Default Description
Node name No No The node type, EmailOutput The name of the node.
Short Description No No   A brief description of the node.
Long Description No No   Text that describes the purpose of the node in the message flow.

Use the EmailOutput node Basic properties are described in the following table.

Property M C Default Description mqsiapplybaroverride command property
SMTP Server and Port No Yes   This property defines the SMTP server and port to which emails are sent from this node, and is in the format server:port; for example: my.smtp.server:25. The port value is optional, but if you do not specify a port value, the default value is 25.

You can specify an alias value for this property. If the alias exists at run time, the specified values are used. If the alias does not exist at run time, the integration node assumes the value to be a valid SMTP host.

You can also set this property to the name of an SMTP policy that contains connection details (see SMTP policy). Specify the name of the policy project and the policy in the format {policyProjectName}:PolicyName.

 smtpServer

The EmailOutput node Email properties are described in the following table.

Property M C Default Description
To Addresses No No   The main recipient or recipients of the email. This property can include a single email address or a comma-separated list of email addresses.
Cc Addresses No No   The carbon copy recipient or recipients of the email. This property can include a single email address or a comma-separated list of email addresses.
Bcc Addresses No No   The blind carbon copy recipient or recipients of the email. This property can include a single email address or a comma-separated list of email addresses.
From Address No No   The email address of the sender of the email.
Reply-To Address No No   The email address to which recipients of the email reply.
Subject of email No No   The subject of the email.
Email message text No No   The main text of the email. Use this property to provide a static main body of an email.

If you use this property, it overrides the content that is provided in the body of the message tree that is passed to the input node. If you do not specify a value for this property, the text of the email is the body of the message tree that is passed to the EmailOutput node.
Body Content Type No No text/plain You can use this property to force the content type for the body of the email message. Valid values are:
  • None
  • text/plain
  • text/html
  • text/xml

The EmailOutput node Security properties are described in the following table.

Property M C Default Description mqsiapplybaroverride command property
Security Identity No Yes   A security identifier to retrieve a user ID and password that are configured at the integration node run time. securityIdentity

The EmailOutput node Attachment properties are described in the following table.

Property M C Default Description
Attachment Content No No   An XPath or ESQL expression that references an element; for example, an element in the message tree, or local environment. The content of the attachment is the value of the element that is referenced.
Attachment Content Name No No   The name of the attachment that is seen by the recipient of the email. This property is optional. If you do not specify a name, a default name is assigned.
Attachment Content Type No No text/plain The type of the attachment. This property is optional, even if you have specified an attachment. Valid values are:
  • text/plain is simple text.
  • text/html is HTML.
  • text/xml is XML.
  • application/octet-stream is the default type for non-text and HTML (binary data).
Attachment Content Encoding No No 7bit The encoding of the attachment. This property is optional. If you do not specify a value, a default encoding is assigned. Valid values are:
  • 7bit is the default value for ASCII text.
  • base64 is used for non-ASCII data, whether it is non-English or binary data.
  • quoted-printable is a more readable-alternative to base64. Use quoted-printable when the majority of the data is ASCII text with some non-ASCII parts. This option provides a more compact encoding because the ASCII parts are not encoded.
Multipart Content Type No No Mixed The type of multipart. Valid values are:
  • Mixed: each MIME body part is independent of the others.
  • Alternative: Each MIME body part is an alternative to the others.
  • Related: All MIME body parts should be considered in the aggregate only.

The Validation properties of the EmailOutput node are described in the following table.

See Validation properties for a full description of these properties.

Property M C Default Description mqsiapplybaroverride command property
Validate Yes Yes Inherit This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit. validateMaster
Failure action Yes No Exception This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List.  
The Monitoring properties of the node are described in the following table.
Property M C Default Description
Events No No None Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node.

You can enable and disable events that are shown here by selecting or clearing the Enabled check box.