doc/README

   1 ==============================================================================
   2 org.ibex.mail
   3
   4 A mail server offering the same level of flexibility as Java Servlets.
   5
   6 The org.ibex.mail server infrastructure is designed to run within
   7 Resin.  This gives us immediate access to Resin's advanced features
   8 including:
   9
  10    - Sophisticated configuration file management in XML
  11       - Expression Language expansion within configuration files
  12    - JNI-driven SSL
  13    - Thread pooling
  14    - Shared configuration of virtual hosts between web-apps and mail-apps
  15    - Authentication infrastructure
  16
  17
  18 ______________________________________________________________________________
  19 JavaScript API
  20
  21 Each script is invoked with the variable 'm' bound to a message to be
  22 handled.  The script MUST return either a Filter or a Target which
  23 will process the message next.  This is a crucial property that
  24 prevents mail from being lost -- a script can never "lose" a message
  25 except by explicitly sending it to the target 'ibex.mail.target.dead'.
  26 All methods which create new messages (such as ibex.mail.message.clone())
  27 Also take a target -- the newly-created message is immediately directed
  28 to the target; the current script does not get access to it.
  29
  30 The following properties are available from ibex.mail:
  31
  32    ibex.mail.
  33
  34              my.                    -- this can be read from but only written to if it is null
  35                 mailbox             -- a mail storage object; subproperties are submailboxes; also qualifies as a Target
  36                 db                  -- a (read/write) properties file for the current user
  37
  38              freshMessageId         -- returns a fresh message id every time it is read
  39
  40
  41              props[path]            -- reads a java-style properties file from [path] and allows read-write access
  42              script[path]           -- reads a script from 'path', parses it as a JS script, and passes the message to that script
  43
  44              filter.
  45                     anonymize
  46                     html2text
  47                     pgp
  48                     singleUseAddress
  49                     returnReciept
  50                     dcc
  51                     vipul
  52                     spamAssassin
  53                     vacation
  54
  55              target.
  56                     dead            -- drops the message on the floor; it vanishes without a trace
  57                     dir[path]       -- uses the directory [path] as a naive file-based storage area
  58                     send            -- sends the outgoing message via smtp
  59                     bounce(message) -- bounces the message
  60                     darcs(repo)
  61                     procmail(procmailrc)
  62                     lmtp(path)
  63                     sms(phone#)
  64                     fax(phone#)
  65                     nntp(group)
  66
  67              message.
  68                      create         -- creates a fresh Message object when read from
  69                      clone(m, t)    -- makes a copy of message 'm' and sends it to target 't'
  70                      pipe(cmdline)  -- pipes the message (headers and body) to the shell command 'cmdline'
  71
  72              crypto.
  73                     base36
  74                           .decode
  75                           .encode
  76
  77
  78
  79 The following tables describe the keys on objects of various types.
  80 The type of an object is not visible from the JavaScript world; it is
  81 provided here only for documentation purposes.
  82
  83 Note that, for example, m.headers.date is not the same as m.date; the
  84 former is a string; the latter is a Date object (with subfields)
  85
  86     Message
  87         allHeaders        [String]  -- one massive string holding all the headers
  88         headers           [Hash]    -- the *string* value of each header, keyed on header name
  89         subject           [String]  -- the Subject: header (for convenience)
  90         date              [Date]    -- the message's date
  91         to                [Address] -- the To: header as an Address object
  92         from              [Address] -- the From: header as an Address object
  93         envelopeTo        [Address] -- the SMTP "RCPT TO:" recipient
  94         envelopeFrom      [Address] -- the SMTP "MAIL FROM:" sender
  95         replyto           [Address] -- the ReplyTo: header as an Address object
  96         messageid         [String]  -- the MessageId: header; if none is present one will be created
  97         cc                [Array]   -- an array of Adress objects, one for each person cc'd
  98         bcc               [Array]   -- an array of Adress objects, one for each person bcc'd
  99         resent            *FIXME*
 100         traces            [Array]   -- an array of Trace objects
 101
 102         deleted           [boolean] -- the message's deleted flag
 103         read              [boolean] -- the message's read flag
 104         answered          [boolean] -- the message's answered flag
 105
 106     Address
 107         user              [String]  -- the 'user' part of 'foo <user@host.com>'
 108         host              [String]  -- the 'host.com' part of 'foo <user@host.com>'
 109         description       [String]  -- the 'foo' part of 'foo <user@host.com>'
 110
 111     Trace
 112         returnPath        [String]  -- FIXME
 113         FIXME
 114