iWay Service Manager > Transport Utility Protocol Adapters > Email

Email

Topics:

Reference:

Email messages typically consist of a set of header fields, an optional body, and an optional set of attachments. The headers contain information about the message, such as to whom it is sent, from whom it was sent, when it was sent, the subject, and so on.

There are several existing email standards. These protocols define how email messages are transferred, the format of the email, and other definitions that enable email to be handled uniformly by various mail servers (which receive and store the mail) and clients (which communicate to the servers to retrieve and read mail messages). The most popular protocols are Simple Mail Transfer Protocol (SMTP), Post Office Protocol (POP3), and Internet Message Access Protocol (IMAP4).

SMTP is a TCP/IP protocol used to send and receive email. However, because it has limited capability of queuing messages at the receiving end, it is usually used with one of the other two protocols, POP3 or IMAP4. These protocols enable users to save messages in a server mailbox and download them periodically from the server. Users usually use software that employs SMTP for sending email and POP3 or IMAP4 for receiving messages retrieved for them at their local server.

POP3 uses a store and forward service. Using POP3, mail is delivered to a centralized server, and users periodically connect to the server to copy or move pending emails to a mobile device. IMAP4 is a client-server mail protocol that enables handling of remote mailboxes as if they were local. With IMAP4, mail is stored on a centralized server and users can copy or move mail to their mobile device. Depending on how IMAP4 is used by a mail server, users can request the server for the headers or bodies of specified messages. Messages remain in the mail repository until marked for permanent deletion. The iWay Adapter for E-mail supports both POP3 and IMAP4 protocols.

The iWay Adapter for E-mail can use the POP3 or IMAP protocols to monitor an email account, select inbound messages, and filter or customize the processing of email based on content using contextual pattern matching of the subject. You can configure the email listener to poll an account at a configured level. The email listener provides support for both preprocessing and postprocessing of both message bodies and attachments.

You can deploy the iWay Adapter for E-mail on all J2EE supported platforms including Windows, Solaris, AIX, and OS/390.

The iWay Adapter for E-mail enables transfer of data to and from an email server. The adapter supports inbound and outbound integration operations. The adapter connects to the email server, extracts data, and converts it to the data types supported by the operation using the conversion instructions in its adapter business object type. Standard iWay processing is then performed. The adapter interacts with the server engine to provide responses from business logic back to the email server. The iWay Adapter for E-mail enables seamless integration of your email servers into your enterprise business processes and enables you to realize a rapid return on investment.

The adapter supports asynchronous bidirectional operations between the adapter and the email server. After receipt of the email, the text in the body of the email is processed. You can then apply standard document analysis, validation, transformation, and business logic capabilities to the document.

You can save attachments to a file or pass them through the system using the provided email emit agent. To process the content in the attachment, you must write a custom agent that implements the applicable business logic.

Note: Email listener behavior was modified from that of previous releases to make it more consistent with the rest of the iWay product line. Previously, it created a document for the body of the email regardless of whether the document was XML or not.

The email listener treats the body of a document like a regular listener. If the body of the email is non-XML, then you must use a preparser to handle the document. If you do not use a preparser, an exception occurs. Alternatively, if the input is non-XML, you can select the Accepts non-XML (flat) only property.

Email Listener Properties

The following table lists and describes the email listener properties. For instructions on creating a listener, see Configuring Listeners.

Property Name

Property Description

Incoming Mail Host (required)

The central repository where electronic mail is stored before the recipient downloads it. This value is obtained from your email administrator.

E-mail User (required)

A valid email account on the server. Requires the user ID, not the complete email address. For example, if the email address is abc@company.com, the email user types abc in the configuration tool.

E-mail Password (required)

A valid password for the email account.

Outgoing Mail Host (required)

The SMTP (Simple Mail Transfer Protocol) host. Location where outgoing electronic mail is placed. Obtain this value from your email administrator.

SMTP User

A valid user name to access the SMTP server.

SMTP Password

A valid password to access the SMTP server.

Subject Filter

The email listener can filter based on the subject header. This listener accepts any email that contains email with the subject in the header. A subject filter of error listens on any pattern that includes the word error. For example, error, RE: error, FWD: error, this is an error, errors.

From Filter

Use this setting if you only want to pick up emails from a specific email address.

Whitespace Normalization

Specifies how the parser treats whitespace in element objects. Select preserve (default) to turn off all normalization as prescribed by the XML Specification. Select condense to remove extra whitespaces in pretty printed documents and for compatibility with earlier versions.

Mail Protocol

The POP3 (default) or IMAP (Internet Mail Application Protocol).

Default iWay User

The user ID included in a request document if not supplied in the body of the email. Use if a simple SQL is supplied in the email.

Default iWay Password

The password included in a request document if not supplied in the body of the email. Use if a simple SQL is supplied in the email.

Default iWay Server

The data source included in a request document if not supplied in the body of the email. Use this if a simple SQL is supplied in the email.

Mailcap File

The location of the email management file that specifies custom classes for processing various email data types (text or images). Do not change unless instructed by server support.

Private Key Entry Alias

The alias for the private key entry for decrypting incoming messages and signing receipts (Message Disposition Notification or MDN). Ensure that you exchange keys with your trading partner and load his or her public key into your key store prior to initiating secure document exchanges.

Private Key Password

The password (if required) for private key. If left blank, then the password for the keystore is used.

From

The email address to put into the From field of the MDN.

Accepts non-XML (flat) only

If set to true, the input data is sent directly to the business logic step. The data is not preparsed, parsed, or validated. This flag is used primarily to send non-XML to the business logic or replyTo without processing it.

Optimize Favoring

Use this option to customize how the listener performs. For smaller transactions, select performance. For large input documents that could monopolize the amount of memory used by iWay Service Manager, select memory.

Multithreading

This indicates the number of worker threads (documents or requests) that iWay Service Manager can handle in parallel. Setting this to a value of greater than 1 enables the listener to handle a second request while an earlier request is still being processed. The total throughput of a system can be affected by the number of threads operating. Increasing the number of parallel operations may not necessarily improve throughput.

Default: 1

Max Value: 99

Maximum Threads

Parallel threads can grow to this count automatically on demand. Over time, the worker count will decrease back to the multithreading level. Use this parameter to respond to bursts of activity.

Execution Time Limit

The maximum time that a request takes to complete. Used to prevent runaway requests. Any request that takes longer to complete than this value is attempted to be terminated. (See the kill interval for related information in Global Options.)

Polling Interval

Indicates the frequency (in seconds) with which the listener polls for a new message or a stop request. The listener is constantly connected to the queue to retrieve incoming messages.

Default: 2.0 seconds.

Default Java File Encoding

The default encoding if an incoming message is not self-declaring (that is, XML).

Agent Precedence

Sets the order by which iWay Service Manager selects agents. iWay Service Manager selects the agent or agents to process the document by searching through the configuration dictionary. Usually, it looks for a document entry in the configuration and when a match is found, the agent specified in that document entry is selected. If a matching document entry is not found, or no agent is specified, the engine looks in the input protocol configuration (listener). To have the processing agent taken directly from the listener (thus ignoring the document entry), use <listener> overrides <document>.

Possible values are <document> overrides <listener> and <listener> overrides <document>.

The default value is: <document> overrides <listener>

Always reply to listener default

If set to true, the default reply definition is used in addition to defined reply-to and error-to destinations.

Error Documents treated normally

If set to true, the error documents are processed by any configured preemitters.

Listener is Transaction Manager

If set to true, agents run within a local transaction. Agents can roll back uncompleted transactions.

Record in Activity Log(s)

If set to true, the activity on this channel is recorded in the activity logs, else the activity will not be recorded.

Reference: Email Listener Special Registers

The following table lists and describes the special registers (SREGs) available on the email listener.

Name

Level

Type

Description

fnfrom

Document

String

The originator of the email with the characters replaced suitable for a file path.

from

Document

String

The originator of the email.

fromaddr

Document

String

The addr portion of from address.

fromalias

Document

String

The alias portion of from address.

to

Document

String

The receiver of the email.

iwayconfig

System

String

The current active configuration name.

msgsize

Document

Integer

The physical length of the message payload.

name

System

String

The assigned name of the master (listener).

protocol

System

String

The protocol on which message was received.

source

Document

String

The originator of the email.

subject

Document

String

The subject of the message.

bcc

Document

String

A Blind Carbon Copy (Bcc) list of recipient addresses of the message (delimited using a semicolon).

cc

Document

String

A Carbon Copy (Cc) list of recipient addresses of the message (delimited using a semicolon).

rcvddate

Document

String

A timestamp indicating when the message was received.

sentdate

Document

String

A timestamp indicating when the message was sent.

tid

Document

String

Unique transaction ID.

Support for Email Attachments

Attachments are files added to an email. Attachments come in many forms, including documents, addresses, calendar entries, programs, software patches, or other pieces of information. Handling attachments on multiple devices is a difficult task. Not all files can run across different device operating systems, and downloading large files is not cost effective in terms of airtime.

Flexibility when handling these message parts is important for any email management system. The iWay email emit agent provides users with the flexibility to efficiently handle messages and message parts.

The email emit agent manages attachments and must be the first agent in an agent chain. The agent optionally adds the attachments to the incoming message or can write the attachments to files on your local system.

For more information on configuring the email emit agent, see the iWay Service Manager User’s Guide.

Configuring an Email Emitter

Reference:

Messages are sent to particular destinations at the completion of a workflow. The state of the document determines which destination is used. The order in which a destination is used cannot be predicted.

Note: Configuring an email emitter is not required if the outlet (emitter) protocol is the same as the inlet (listener) protocol.

To route an output document or error message to a protocol other than that of the outlet (listener), you must configure an emitter. For example, an application can send input over TCP, but you want to route the output to an email queue.

Reference: Email Emitter Properties

The following table lists and describes the email emitter properties. For instructions on creating an emitter, see Configuring Emitters.

Property

Description

Destination (required)

The email address of the intended recipient.

Outgoing Mail Host (required)

The Simple Mail Transfer Protocol (SMTP) host. This is the location where outgoing electronic mail is placed. Obtain this value from your email administrator.

E-mail User

The user name at the host that can send emails, if the system is a secured email system.

E-mail Password

The password associated with the email user, if the system is a secured email system.

Subject of Msg

The value to insert in the email subject header.

Sender address

The email address of the sender of the message.

Copy To

The optional copy to email address. You can supply multiple email addresses (separated by commas).

Blind Copy To

The optional blind copy to email address. You can supply multiple email addresses (separated by commas).

Content Type

The content type headers for the payload based on MIME standards. For payload, the header is prefixed by application. Use the drop-down list for the preconfigured list of payload types, or type your preferred content type in the entry box.

Security Protocol

Indicate whether to use a security protocol. You can choose from the following:

  • None. Uses a clear SMTP connection.
  • SMTPS. Connects to a secure SMTP server.
  • STARTTLS. Connects to an unsecured SMTP server, then negotiates an SSL/TLS connection.

Packaging (required for S/MIME)

The type of data packaging. This value defines how the payload of the MIME message is packaged. Transmission options are:

  • Regular: No special packaging.
  • Signed: The MIME headers are applied and the document is signed digitally using the server private key (the recipient of the message must have the public key of the signer to validate the signature).
  • Encrypted: MIME headers are applied and the business document is encrypted using the public key of the trading partner. The trading partner's public key must be stored in the keystore, and an alias supplied in Public Key Entry Alias entry.
  • Signed and encrypted: The message is signed (using the private key) and encrypted (using the public key of the trading partner).

Compression

If set to true, applies document compression.

Request Receipt (required for S/MIME)

The type of receipt (MDN) required. Options are as follows:

  • None: No MDN required.
  • Unsigned: An unsigned MDN is required.
  • Signed: An MDN signed by the recipient is required (the public key of the trading partner is required to be stored in the keystore file). Signed receipts ensure non-repudiation of the message (for example, that you received the receipt from whom you believed sent it, based on the public/private key pair based validation).

Deliver Receipt To

This is required if asynchronous MDN is also required. For example, MDN is not delivered to the sending email address (specified in the sender address box).

Public Key Entry Alias

The public key entry alias for the trading partner receiving encrypted messages (as defined on the import process into the keystore).

Private Key Entry Alias

The private key alias for the server certificate.

Private Key Password

The password for the private key (if required). If left blank, the password for the keystore file is used.

Digest Algorithm

The message digest algorithm used for creating the digital signature. Options are as follows:

  • MD5 (Message Digest Algorithm)
  • SHA1 (Secure Hash Algorithm Version 1)

Encryption Algorithm

The algorithm that encrypts the payload (business document). The options are as follows:

  • Des-ede3 (known as triple des)
  • Rc2 (the default setting)
  • Idea
  • Cast5

Email Troubleshooting

The following table lists and describes errors that you may encounter when using an email listener.

Error

Reason

Solution

 
unable to connect: 
javax.mail.AuthenticationFailedException: 
Password supplied for iwaytest7 is 
incorrect.: [line 6]

User ID or password specified is incorrect.

Log on to the email account using an email tool to verify that the user ID and password specified in the configuration console are correct. 

Unable to connect: 
javax.mail.MessagingException: Connect 
failed; nested exception is:        
java.net.UnknownHostException: ibirisc21: 
[line 3]

Server is unable to connect to the incoming mail server (POP3 Server).

Use the configuration console to verify that you have correctly entered the POP3 Server. To verify the POP3 Server name, contact your email administrator. 

Unable to connect: 
javax.mail.MessagingException: Connect 
failed; nested exception is:         
java.net.UnknownHostException: 
ibi.com@ibirisc2: [line 3] unable to 
login: [line 3]

Unable to log on to the POP3 Server.

Verify that the user ID is correct. Verify that it is in the format of user name, and not username@host.com.