======Quarantine Report Mailer Scripting======
(Added in v9.1)

This script is called when VPOP3 is mailing out (or considering mailing out) spamfilter quarantine reports. It allows customisation of the emailed reports and whether they're generated

====AreMailsNeeded====

  function AreMailsNeeded(lastTimeEmailsSent)
  
returns mailsNeeded, untilTime

  * mailsNeeded = boolean, true = send emails, false = don't send emails
  * untilTime (optional) = latest date/time of the quarantined items to include in the emails in the form "yyyyMMddHHmmss"

If this function doesn't exist, then it works on the configured schedule, and includes items up to the current time

====GetMsgLimit====

  function GetMsgLimit(username, itemLimit)
  
returns newItemLimit

This is called for each user, and indicates how many items will be included in the quarantine report emails (default 5000)


====GetSortOrder====

  function GetSortOrder(username, existingSortOrder, numberOfItems, quarantineItems)
  
This is called for each user to whom an email will be sent, and allows customisation of the sorting of the items on the email.

returns newSortOrder

Possible sort orders are:
  * Time
  * Sender
  * Subject
  * Size
  * Score

quarantineItems is a table of items, where each is:
  * Id - internal ID (string)
  * Sender (string)
  * SenderName (string)
  * Date (string)
  * Time (string)
  * Subject (string)
  * Size (number, in bytes)
  * Score (number)

====GenerateMessage====

  function GenerateMessage(username, quarantineItems, numberOfItems, limitReached, userSettings)
  
returns messageSubject, messageTextContent, messageHtmlContent

This allows the script to generate the entire quarantine report message. If all three items are returned, then it overrides the automatic generation, otherwise VPOP3 will generate using the other settings/script results

====GetHtmlTemplate====

  function GetHtmlTemplate(username, quarantineItems, numberOfItems, limitReached)
  
returns filename, templateContents

  * filename = a list of possible filenames to use. VPOP3 will pick the first which exists as the template for the HTML part of the message
  * templateContents = the content of the HTML template. If this is not empty, then VPOP3 will ignore the 'filename' value

===Filename===
"filename" contains a list of or more filenames, separated by ';'. In a filename '%base%' is replaced by the installation directory, '%temp%' is replaced by the temporary directory (usually the _temp subdirectory), '%exe%' is replaced by the directory where VPOP3.EXE is installed

==Template format==
The template file or "templateContents" should contain the HTML source for the email. It can contain control sequences

  * ~rows:<row class list>~ - this contains a comma-separated list of CSS classes which are applied to rows. Eg the default is ',,,lt,lt,lt' so that for each set of 6 rows, the first 3 have no class, and the second 3 have the class 'lt' applied
  * ~rowtemplate~<template>~end~ - this sets the template for each row in the quarantine report table. It is a text string with text replacements:
    * %1!s! - date
    * %2!s! - time
    * %3!s! - sender email address
    * %4!s! - sender text name
    * %5!s! - row CSS class (from '~rows~' above)
    * %6!s! - spam score CSS class (safe, ok, bad or vbad)
    * %7!s! - subject
    * %8!s! - size (text because it's converted to kB etc)
    * %9!ld! - score
    * %10!s! - URL to view/release message
  * ~insert~ - where the generated report table is inserted
  * ~user~ - username
  * ~date~ - date
  * ~count~ - number of items
  * ~localdomain~ - VPOP3 local domain
  * ~colour0~, ~colour1~, ~colour2~, ~colour3~ - colours in report
  * ~spamforward~<data>~end~ - <data> is added if forwarding to spam filter is allowed
  * ~limitreached~<data>~end~ - <data> is added if the row limit was reached
  * ~comment~<data>~end~ - removed during processing - useful for comments for later reference when maintaining the template

====GetHtmlOptions====

  function GetHtmlOptions(username, quarantineServer, colour0, colour1, colour2, colour3)
  
returns newQuarantineServer, newColour0, newColour1, newColour2, newColour3

====GetTextTemplate====

  function GetTextTemplate(username, quarantineItems, numberOfItems, limitReached)
  
returns filename, templateContents

  * filename = a list of possible filenames to use. VPOP3 will pick the first which exists as the template for the Text part of the message
  * templateContents = the content of the Text template. If this is not empty, then VPOP3 will ignore the 'filename' value

For "filename" see GetHtmlTemplate section above
==Template format==
The template file or "templateContents" should contain the Text source for the email. It can contain control sequences

  * ~insert~ - where the generated report table is inserted
  * ~user~ - username
  * ~date~ - date
  * ~count~ - number of items
  * ~localdomain~ - VPOP3 local domain
  * ~link~ - link to page containing quarantine report - for release/viewing of messages
  * ~spamforward~<data>~end~ - <data> is added if forwarding to spam filter is allowed
  * ~limitreached~<data>~end~ - <data> is added if the row limit was reached
  * ~comment~<data>~end~ - removed during processing - useful for comments for later reference when maintaining the template