citadel/docs/delivery-list.txt

   1 Description of the custom MIME type "application/x-citadel-delivery-list"
   2
   3  This MIME type may be found in the outbound queue room on Citadel systems,
   4 which is typically called "__CitadelSMTPspoolout__".  The room is flagged as
   5 a "system" room, which means that it's completely hidden to everyone, although
   6 an Admin can get to it if the full name is specified (but unlike a normal
   7 hidden room, it does not appear in the known rooms list on subsequent visits).
   8
   9  Messages in this format contain delivery instructions.  Therefore, for each
  10 message in the queue to be delivered to one or more recipients, there will be
  11 *two* messages in the room: one containing the actual message, and the other
  12 containing delivery instructions.  It is expected that the instructions
  13 message may be replaced at any time (using an Exclusive ID field) if delivery
  14 to only some of the recipients has been accomplished.
  15
  16  Citadel keeps reference counts of each message on disk.  Therefore if a
  17 message contains a mixture of local and remote recipients, there may be two
  18 or more references to the message itself, one of them being the one in the
  19 queue.
  20
  21  A delivery list contains one or more lines of text, each line containing
  22 a single instruction (usually a recipient).  Fields are separated by the
  23 vertical bar character ("|") and there will always be at least one field on
  24 each line.
  25
  26  When delivery to all listed recipients has either completed or permanently
  27 failed, both the queue item and the message itself are deleted from the
  28 queue room.
  29
  30  -- Once per queue item --
  31
  32  INSTRUCTION:  msgid
  33  SYNTAX:       msgid|0000000
  34  DESCRIPTION:
  35     Defines the actual message for which we are providing delivery
  36     instructions.  This instruction must precede all the others.  When
  37     all deliveries have either succeeded or failed, both the instructions and
  38     the copy of the message itself in the queue room should be deleted.  The
  39     second parameter specifies the message ID in the local database.
  40
  41
  42  INSTRUCTION:  submitted
  43  SYNTAX:       submitted|999999999
  44  DESCRIPTION:
  45     Contains a timestamp designating when this message was first entered into
  46     the system.
  47
  48
  49  INSTRUCTION:  attempted
  50  SYNTAX:       attempted|999999999
  51  DESCRIPTION:
  52     Contains a timestamp designating the date/time of the last delivery
  53     attempt.
  54
  55
  56  INSTRUCTION:  retry
  57  SYNTAX:       retry|9999999
  58  DESCRIPTION:
  59     Citadel does not retry SMTP delivery at a fixed interval.  Instead, it
  60 starts at a nominal interval (15 minutes by default) and then doubles the
  61 interval after each failed attempt.  This instruction contains the interval
  62 which should currently be followed (and doubled again, if the next delivery
  63 fails).
  64
  65
  66  INSTRUCTION:  bounceto
  67  SYNTAX:       bounceto|Big Bad Sender[@host]
  68  DESCRIPTION:
  69     Where to send "bounce" messages (delivery status notifications).  The
  70     contents of the second field are supplied as the "recipient" field to
  71     CtdlSaveMsg(), and therefore may be a local username, a user on another
  72     Citadel, or an Internet e-mail address.
  73
  74
  75  INSTRUCTION:   envelope_from
  76  SYNTAX:        envelope_from|blurdybloop@example.com
  77  DESCRIPTION:
  78     Sets a value to be used as the envelope sender during the 'MAIL FROM:'
  79     phase of the SMTP transaction.  If an envelope sender is not supplied,
  80     one is extracted from the message body.
  81
  82  INSTRUCTION:   source_room
  83  SYNTAX:        source_room|Citadel Support
  84  DESCRIPTION:
  85     when sending mailinglist rooms this contains the source room for displaying
  86     and messaging purposes.
  87
  88
  89
  90
  91 -- Once per recipient per queue item --
  92
  93  INSTRUCTION:  remote
  94  SYNTAX:       remote|friko@mumjiboolean.com|0|delivery status message
  95  DESCRIPTION:
  96     Names a recipient on a remote system to which the message should be
  97     delivered.  The third parameter may contain any of the following values:
  98        0 = No delivery has yet been attempted
  99        2 = Delivery was successful
 100        3 = transient error state; like connection failure or DNS lookup failure
 101        4 = A transient error was experienced ... try again later
 102        5 = Delivery to this address failed permanently.  The error message
 103            should be placed in the fourth field so that a bounce message may
 104            be generated.