The SMTP Listener

Similar to the coils.workflow.9100 service that can deliver raw socket connections into defined workflows OpenGroupware Coils also provides an SMTP listener. The listener enables workflows to receive messages via SMTP; simply configure your MTA (Mail Transfer Agent) to route some prefix such as "ogo" to your OpenGroupware Coils instance and then use plussed address syntax to deliver e-mail messages to specific objects.

Workflows can be invoked using ogo+wf+routeName@ syntax; for example to send an e-mail message to the workflow named ExampleStatusUpdate a message would be sent to ogo+wf+examplestatusupdate@example.com. In the case of a workflow the text/plain body of the message will become the input message for a new instance (Process) of that route. A ticket is open to implement support for receiving specific MIME-types attached to a message as the process' input message.

To target an entity with a message, assuming your delivery is routing ogo@ to the OpenGroupware Coils listener, send a message to ogo+objectId@example.com where objectId is the numeric object id of the entity. In most cases the entity must allow read access to the NetworkContext (OGo#8999) via an ACE in the object's ACL. OpenGroupware Coils network service components interact with the object model with the NetworkContext, this security context has minimal access to the server's objects and content for obvious security reasons. Additional access must be deliberately granted to allow unathenticated services such as the socket and SMTP listener to interact with an object.

Document folders are one entity that supports receiving messages from the SMTP listener. In order to access the folder the NetworkContext must have read access to the folder entity and in order to actually store content in the folder it must have write access. For this reason it is recommended that a specific folder be created in a project for the purpose of receiving SMTP messages; from that folder a user, application, or workflow can relocate and possibly rename the documents.

For example, a message sent to ogo+1234567@example.com, where OGo#1234567 is a document folder to which NetworkContexts has read/write permissions, will be stored in its raw form in that folder. Most document-oriented applications however cannot easily deal with raw e-mail messages [after all, they aren't e-mail clients]. Perhaps what you really need is some document that is attached to these e-mail messages? This is a common use case with document centers - they scan documents into PDF and delivery them via SMTP. In order to facilitate this use-case and to streamline document management the user or application can define the MIME type of the documents the folder should receive. If a MIME type is defined for SMTP collection on a folder than only that type of document, attached to a received message, will be saved - the attachments will be automatically saved from the message and the message itself discarded.

In order to define a MIME-type for SMTP collection on a folder create an object property in the http://www.opengroupware.us/smtp namespace having an attribute name of collectMIMEType. The value of that property should be the MIME-type you desire to collection. For example, if {http://www.opengroupware.us/smtp}collectMIMEType was defined on OGo#1234567 [from our previous example] having a value of "application/pdf" then only PDF attachments would saved to the folder. There are two special-case MIME-types:

• message/rfc822 - This is the default type, and just as if the object property were not defined, will cause incoming messages to be saved in their entirety.
• text/plain - This value will save the text/plain message body as a document in the folder.

On every document created by the SMTP listener a set of object properties will be created. These properties correspond to headers in the e-mail message from which the document was created; if a corresponding header does not exist in the e-mail message than the corresponding object property will not be created. The SMTP listener defines a set of interesting headers; if you believe there are headers that should be captured but are not included in this list feel free to request the addition of the header via the projects' ticket application of SourceForge.

The currently defined list of object properties created from message headers are:

• {us.opengroupware.mail.header}subject
• {us.opengroupware.mail.header}x-spam-level
• {us.opengroupware.mail.header}from
• {us.opengroupware.mail.header}to
• {us.opengroupware.mail.header}date
• {us.opengroupware.mail.header}x-spam-status
• {us.opengroupware.mail.header}reply-to
• {us.opengroupware.mail.header}x-virus-scanned
• {us.opengroupware.mail.header}x-bugzilla-classification
• {us.opengroupware.mail.header}x-bugzilla-product
• {us.opengroupware.mail.header}x-bugzilla-component
• {us.opengroupware.mail.header}x-bugzilla-severity
• {us.opengroupware.mail.header}x-bugzilla-status
• {us.opengroupware.mail.header}x-bugzilla-url
• {us.opengroupware.mail.header}x-mailer
• {us.opengroupware.mail.header}x-original-sender
• {us.opengroupware.mail.header}mailing-list
• {us.opengroupware.mail.header}list-id
• {us.opengroupware.mail.header}x-opengroupware-regarding
• {us.opengroupware.mail.header}x-opengroupware-objectid
• {us.opengroupware.mail.header}x-original-to
• {us.opengroupware.mail.header}in-reply-to
• {us.opengroupware.mail.header}cc
• {us.opengroupware.mail.header}x-gm-message-state
• {us.opengroupware.mail.header}message-id

All documents created will have at least the property {us.opengroupware.mail.header}message-id as Message-ID is a required header [per RFC822]. The SMTP component will not process a message that lacks a Message-ID header. The Message-ID and a timestamp are used to create the documents filename.

In addition to these properties the property {http://www.opengroupware.us/mswebdav}contentType used by the WebDAV presentation will also be set on created documents to store the original MIME-type.

These properties can be used to correlate or qualify the documents, and [of course] can be used as search qualifications when using zOGI's searchForObjects.

Document creation by SMTP provides for a very simple integration path with innumerable both consumer and enterprise level devices. From there your applications can easily access the documents by zOGI (JSON-RPC or XML-RPC), AttachFS (REST), or WebDAV.

Author: Adam Tauno Williams