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