Pop3

This connector polls an email account via the POP3 protocol, and presents emails as new event data. (Only emails containing text or HTML content are supported.) The event data has the format shown below. The exact same email is shown twice, once for "pop.concatenate.message" set to true, and then false. Note the difference in the way the "content" section is formatted.

<email from="crystal@noc.corp.con" contentType="text/plain" dateSent="Date=Tue Oct 27 15:44:16 EDT 2009">
<subject>Network status update for corporate NOC</subject>
<content>Servers: up=72; down=3; maintenance=10. Domain=noc.corp.con  Best regards, Your SNMP device manager</content>
</email>

pop.concatenate.message=true

<email from="crystal@noc.corp.con" contentType="text/plain" dateSent="Date=Tue Oct 27 15:44:16 EDT 2009">
<subject>Network status update for corporate NOC</subject>
<content><![CDATA[
Servers: up=72; down=3; maintenance=10.
Domain=noc.corp.con

Best regards,
Your SNMP device manager
]]></content>
</email>

The contentType attribute will be equal to (or begin with) either "text/plain" or "text/html". For example, a full contentType value might be "text/plain; charset=us-ascii; format=flowed" All other content types are ignored by this implementation. When pop.concatenate.message=false, the content appears in its original format, but enclosed in a CDATA block (an XML feature used for raw data).

The dateSent attribute is obtained from an optional message header. If this header is not available, then this attribute will not appear in the event format.

The from attribute may contain a long-form email address, e.g. "Shine E. Crystal <crystal@noc.corp.con>"

POP3

Note that POP3 servers do not support per-message flags, such as "has been read". Therefore, all POP3 email clients, including this plug-in, must track messages as they are read. This current implementation only remembers previously read messages for as long as the gateway is running. So even if you set pop.messages.unreadonly=true, the old messages will be re-processed once, each time you restart a gateway. This limitation is less important if you set pop.retain=false, so that messages are deleted as they are read.

Also note that POP3 does not provide a date for when the message was "received" by the server, (unlike other protocols).

Caveats

The event format is not strictly XML compliant. Some trade-offs were made for ease of Augur parsing. In particular:

• The email content starts and ends on fresh lines (unless you set pop.concatenate.message=false in which case the whole content is on one line anyway). This means that technically, the content will have been altered by inserting a new line before and after the content.
• The "subject" text is not encoded to eliminate illegal XML characters, such as "<" and "&".
• The same as above applies for the "content" text if you set pop.concatenate.message=true
• If you set pop.concatenate.message=false then the raw email content is wrapped in a "CDATA" block, which avoids the above problem. However, note there is no effort to encode "]]>". If that string appears within the content, then it technically breaks the formatting rules of XML.

Debug