-----------------
A "message sequence" is a handle by which one may refer to a particular subset of a mail recipient's (player or $mail_recipient-descendant) saved messages. Routines like rcpt:display_seq_headers or rcpt:display_seq_full need to be supplied with message-sequence arguments to deterimine which headers or full-messages to display.
Message sequences can in turn be obtained from routines like rcpt:parse_message_seq, which takes a command-line description of a message sequence on that particular recipient and returns the corresponding message sequence handle.
The actual form of a message sequence (though you shouldn't actually need to make use of this) is that of a set of integers in the format used by $seq_utils (see `help $seq_utils'). It should however be noted that these integers are *not* themselves message numbers, but rather indices into the list of saved messages. For example, if a particular recipient holds 5 messages numbered 1,3,5,7,9. Then the message sequence handle representing messages 3,5,7 collectively, would be {2,5} which is $seq_utils-ese for the range 2..4, namely the second, third and fourth messages saved on that recipient.
The following verbs are available for obtaining indices to use in message sequences
:length_all_msgs() => total number of messages, or equivalently,
=> index of last message
:length_num_le(n) => number of messages numbered <= n, or equivalently,
=> index of highest numbered message <= n
:exists_num_eq(n) => 0 unless there exists a message numbered n in which
case we return the index of that message.
:length_date_le(date) => number of messages dated <= date, or equivalently,
=> index of most recent message dated <= date
:length_date_gt(date) => number of messages dated > date
Note that r:length_date_gt(date) == r:length_all_msgs()-r:length_date_le(date).
The only reason :length_date_gt is provided as a separate routine is in order
to do quick checks for the existence of new mail (as @rn needs to do).