This Mailbox Connector provides access to internet mailboxes (POP3 or IMAP). The Mailbox Connector can be used in AddOnly, Iterator, Lookup, Update and Delete modes. The Mailbox Connector uses predefined attribute names for the headers that are used most often. If you need more than this,f use the mail.message property to retrieve the native message object.
On initialization, the Connector gets all available mail messages from the mailbox on the server and stores them into an internal Connector buffer. Later the Connector retrieves the messages one by one on each getNextEntry() call; that is, on each Iteration. When all the messages from the buffer have been retrieved, the parameter Poll Interval governs what happens next; see Configuration. This is different from earlier implementations of this Connector.
If the IMAP protocol is specified the Mailbox Connector registers for notifications for messages added and messages removed from the mailbox on the server. When a notification that a message has been added to the mailbox is received, the Connector adds this message to its internal buffer. If a notification that a message has been removed from the mailbox is received, the Connector removes this message from its internal buffer.
For all supported modes except Addonly (Iterator, Update, Lookup, Delete) the Mailbox connector iterates on all folders in the mailbox, if no folder is specified in the configuration. Otherwise, there is the option to iterate on subfolders of the supplied folder. In both cases you can specify a list of comma-separated folders to be excluded when browsing the mailbox.
The user's mail folder stores the user's mail messages on the mail server. When using the POP3 mail protocol specify "INBOX" as the value for this parameter. When using the IMAP mail protocol you can specify any mail folder which exists on the mail server.
After the AssemblyLine consumes all mail messages stored in the Mailbox Connector buffer, the Connector sleeps for a while and then reconnects to the mail server and checks for new messages. In other words, the Connector polls the server for new mail messages.
A special value of "-1" means that the Connector will not poll for new mail messages after the initial poll. This means that the AssemblyLine will terminate after it has consumed all messages retrieved by the Connector on the initial poll.
The Mailbox Connector uses the following predefined attributes and properties, which are available in the Input Map:
The Mailbox Connector gets the following Attributes from the work Entry (Output Attribute Map):
In this mode the Connector is iterating through all messages from the specified folder (INBOX by default). Each message will be translated into an entry and its attributes will be available for the next step of the flow.
Depending on the backend mail server you are connecting to, you might not be able to interact directly with the body of a message. This is because the server supports multi-body parts, as opposed to a single one. In this case all the body parts can be accessed as a multi-valued attribute (for example,
where N is the number of the message body, the number zero indicating the first message body). In case the server does not provide multi-body parts then the message body will be in the attribute mail.body.
If no folder is specified, then the Connector iterates through all mailbox folders. A parameter allows for configuring that certain folders can be skipped when iterating. The names of these folders are entered in a text box separated by comma. Another parameter defined as a checkbox is used to indicate whether the Connector also should iterate through the subfolders of the specified folder. Note that when POP3 is chosen this option is not available, since the POP3 provider supplies a single folder - "INBOX". If the Mail Folder parameter is left empty, the Connector will iterate on the messages in the INBOX folder.
In this mode the retrieved Entry(s) are based on the LinkCriteria defined for the connector. In case no message is found then an exception is thrown. This mode is similar to Iterator mode but here you can not iterate through the messages in the mail folders unless you have LinkCriteria defined. The attributes mapped in the work entry will be filled in if a single message is found. If more than one entry is returned then the AssemblyLine execution will stop; you can work around this by providing logic for cases like this in the 'On Multiple Entries' Hook.
When the Mailbox Connector is used in Lookup mode the only searchable headers are:
In this mode the entry(s) returned are based on the defined LinkCriteria. In one message is found then it is deleted. If no messages are found then either 'On No Match' Hook is called (if defined) or an exception is thrown and execution stops. If more than one message is found then either 'On Multiple Entries' Hook is called (if defined) or exception is thrown.
When the Mailbox Connector is used in Delete mode the only searchable headers are:
AddOnly mode is used for putting messages into a specified mailbox folder. For this purpose first configure the mail server, mail credentials, protocol type (only IMAP) and the folder in which the new messages will be delivered.
This mode can only be used with IMAP protocol since the POP3 protocol does not support appending of messages. For more information about the restrictions of the POP3 provider for the Java Mail API refer to: http://java.sun.com/products/javamail/javadocs/com/sun/mail/pop3/package-summary.html.
In case the folder defined in the configuration of the Connector does not exist, the parameter "createFolder" is taken into account. If it is checked and the supplied folder is not present, a new one with this name is created. The new Messages are delivered to the connector in an attribute called mail.addMessage; this attribute is passed an Object of type javax.mail.Message or an array of that type. The Connector connects to the mail box and appends the message(s) into the specified folder.
In update mode the Mailbox Connector is able to make changes to the flags of a message in the specified mail folder. The supported flags are: Answered, Deleted, Draft, Recent and Seen. These parameters are passed to the Connector as Attributes in its output map. Flags and therefore the corresponding Attributes are of Boolean type. The Flags can be manipulated through the javax.mail.Message.setFlag(...) method.
You specify in the work entry which flag should be updated and the new value. In case the message store does not support the flag that you want to update, a message is logged containing the flag attribute for which the operation failed. Afterwards the connector continues with the updates of the other flags.
When the Mailbox Connector is used in Update mode the only searchable headers are: