###
# PATCHED VERSION
###

Requirements:
-------------
- msmtp
- ping
- at (and daemon active)
- pcregrep

Install:
--------
  copy the msmtpq and msmtp-queue scripts to the directory where they will live
    be certain that they are executable
      ( chmod +x msmtp* )
      ( sudo cp msmtp* /usr/local/bin/ )
  create the queue dir (0700) if necessary
    ( mkdir -p /path/to/queue/dir )
    ( chmod 0700 /path/to/queue/dir )
  enter or confirm the values of the three config setup vars in msmtpq
  enter or confirm the values of the three option vars in msmtpq - if desired
  for mutt users -
    set sendmail="/path/to/msmtpq"   (or "ANY_ENV_VARS_HERE=t /path/to/msmtpq")
    unset sendmail_wait  (you might have  error to catch)
    set use_from=yes
    set realname="Your Name"
    set from=you@example.com
    set envelope_from=yes
    (and perhaps more on the msmtp man page & docs ...)

Introduction:
-------------
The present patch schedules sending email to a default value of 3 minutes in
the future and the date of the email will be set accordingly. It is yet
possible to change that default value by adding the "Scheduler: ..." header
(key "E" in the sending menu) and put the "at" syntax in it (eg: now, 9 AM
tomorrow, ...).  The header is used as a trick to easily pass scheduling
to msmtpq but in the future a more elegant solution should replace it.

How to Cancel an Email:
-----------------------
run atq command, then atrm <pid> (see man at). You can then modify both
file.mail and file.at, remove the file.sch and run the msmtp-queue -r command
to schedule againg that email.

How to Verify the mail was sent:
--------------------------------
Look at the logfile: "at" will log the result of msmtp. You can also look at
atq command within the delay to check the scheduler is active fine.

How to Schedule something else than 3 minutes:
----------------------------------------------
Press "E" in the sending menu. Add the header "Scheduler: <my at syntax>".
eg: 4pm + 3 days, 1am tomorrow, midnight, 6pm today (more running man at)

What if my scheduling syntax is wrong ?
---------------------------------------
Mutt will alert you, and you will be able to edit the "Scheduler" header. You
will also have an error in the logs.

What if you are offline ?
-------------------------
The mail will be put in the queue but won't be scheduled. Running msmtp-queue
-r when online will schedule the email. 

Good Practices:
---------------
- It might be a good option to cron regularly the msmtp-queue -r command.
- Parse regularly the logs to detect when semething went wrong.


###
#   **The below information are not up to date anymore**
###


msmtpq is a modification of the scripts comprising part of Martin Lambers'
msmtpqueue package ; it attempts be useful to msmtp by holding mail sent
by an MUA when a system, e.g. a laptop, is not connected to the net ;
queued mails are held as files in a user defined and created queue
directory ; when the machine is connected all mail can be sent directly
out ; the msmtpq package does queue handling for msmtp according to the
way the queue is used

  msmtpq        accepts mail input from an MUA (e.g. mutt) and sends it
                directly out via msmtp if possible - or queues it if not

  msmtp-queue   is a wrapper script which simply calls msmtpq with the
                --q-mgmt argument ; it exposes routines for queue
                management and maintenance, that is, for queue display,
                queue run (flush), mail purge from the queue, etc.

msmtp-queue is interactive at the command line while msmtpq, called
directly, has no interactive user input whatever - it simply takes its
input from the MUA and outputs directly to msmtp (or to the queue)

credit goes to Martin Lambers for the idea of the queue ; any bugs,
design errors, oversights, suggestions for improvement, etc. belong to
me ; all feedback is welcome ; I can be reached via the msmtp mailing
list


Installation :
------------

copy msmtpq and msmtp-queue to whatever location is best for you
(I use /usr/local/bin) ; the directory chosen should be on the path

replace the msmtp invocation in your mail client with msmtpq ; e.g. for
mutt : 'set sendmail = /path/to/msmtpq'

msmtpq will then take care of the management and routing of outgoing
mail ; normally sending a mail is nearly instantaneous, but a very long
mail (e.g. one with large attachments) can take some time to make its way
through ; therefore it's wise to have the MUA background the process if
possible

In the case of mutt, in addition to the above setting,

'set sendmail = /path/to/msmtpq'

set, also,

'set sendmail_wait = -1'

mutt then backgrounds the send and watches for a return code & message
from msmtpq


Configuration :
-------------

all config is done within the msmtpq script

  set the MSMTP var to point to the location of the msmtp executable
    (set this only if necessary ; if it's not on the path)
  set the Q var to point to the location of the queue directory
  set the LOG var to point to the location of the queue log

the MSMTP variable can have the location of the msmtp executable entered
into it if it is not on the path ; this might be useful in unusual
circumstances, such as embedded systems, etc. ; otherwise, if you are
running a normal Linux distribution you can leave it as is ; msmtp will
by default be on the execution path

the Q variable should have the location of the queue directory

the LOG variable should have the desired name & location of the queue log

the locations are clearly marked near the beginning of the script ;
modify all to the locations you prefer (the defaults work for me ; you
may or may not be happy with them) ... please note that it's preferable
to create the queue directory (with 0700 permissions) before using these
routines

note that the default msmtpq set up creates a separate log for queue
operations ; all operations which modify the queue in any way are logged
to the queue log ; this is distinct from the msmtp log set by the
'logfile' setting in .msmtprc ; I've been persuaded that it's better to
have separate logs (for the distinct functions) ; if this doesn't sit
well with you it's possible to define the queue log to be the same log
file as the one defined in .msmtprc ; it's also possible to turn off
queue logging entirely (by commenting out the 'LOG=' var - to be
'#LOG=') but this seems hardly advisable, particularly before you are
confident that all is working

mutt users please take note of the additional setup instructions in the
msmtp docs & man page.


to use msmtpq with additional options :

the vars : EMAIL_CONN_NOTEST (to test for a net connection or not
                              before attempting to send a mail)

                             (please note that the above var is deprecated
                              and will be removed in a future version of msmtpq ;
                              replace it with EMAIL_CONN_TEST=x
                              to perform the same function)

           EMAIL_CONN_TEST   (which test for net connection to use)
           EMAIL_QUEUE_QUIET (suppress unnecessary queue 'chatter')

see below for their values

there are two methods of setting options -


- set the vars in the msmtpq script (near the top)

  see the script, just beneath the the three setup vars mentioned above

- set the vars externally to the script

    define the variables as environment vars, set on the command line
      invoking msmtp

set sendmail = "/path/to/msmtpq"
                 # normal config for mutt to use the queue
                 # (by default the ping connection test is enabled)

set sendmail = "EMAIL_CONN_TEST=x /path/to/msmtpq"
                 # use queue without a net connection test
set sendmail = "EMAIL_CONN_TEST=p /path/to/msmtpq"
                 # use queue with ping connection test (the default)
set sendmail = "EMAIL_CONN_TEST=P /path/to/msmtpq"
                 # use queue with faster ping connection test
                 # (to an IP address, without a DNS lookup)
set sendmail = "EMAIL_CONN_TEST=n /path/to/msmtpq"
                 # use queue with netcat connection test
                 # (netcat must be installed on user's system)
set sendmail = "EMAIL_CONN_TEST=s /path/to/msmtpq"
                 # use queue with sh sockets connection test
                 # (this does *not* work on Debian systems ;
                 #  socket use is not compiled into bash for
                 #  security reasons on multiuser systems - it
                 #  may not be a serious consideration, however, on
                 #  single user workstations - e.g. on laptops -
                 #  or in embedded systems)

set sendmail = "EMAIL_QUEUE_QUIET=t /path/to/msmtpq"
                 # use queue ; suppress messages and 'chatter'
                 # good, apparently, for use w/emacs MUAs

set sendmail = "EMAIL_CONN_TEST=? EMAIL_QUEUE_QUIET=t /path/to/msmtpq"
                 # use queue w/connection test spec &
                 # suppression of messages and chatter

externally multiple environmental vars may be used on the command
  line, space separated, before the msmtpq invocation ; internally
  to the script multiple vars may be set

note that vars set internally will take precedence over vars set
  externally

if no option is specified, by either method, the net connection test
  is made using the ping test by default


in summary :
  copy the msmtpq and msmtp-queue scripts to the directory where they will live
    be certain that they are executable
      ( chmod +x msmtpq msmtp-queue )
  create the queue dir (0700) if necessary
    ( mkdir -p /path/to/queue/dir )
    ( chmod 0700 /path/to/queue/dir )
  enter or confirm the values of the three config setup vars in msmtpq
  enter or confirm the values of the three option vars in msmtpq - if desired
  for mutt users -
    set sendmail="/path/to/msmtpq"   (or "ANY_ENV_VARS_HERE=t /path/to/msmtpq")
    set sendmail_wait = -1
    set use_from=yes
    set realname="Your Name"
    set from=you@example.com
    set envelope_from=yes
    (and perhaps more on the msmtp man page & docs ...)
  for other MUAs -
    set the mta to '/path/to/msmtpq', as above and
    background its execution, if possible

msmtpq is entirely self contained ; beyond keeping an eye on the queue
  and queue logs it should require no admin or user attention once set up


log(s) rotation :

On a Debian or Debian-based system (e.g. Ubuntu or Mint) a file can be
created in /etc/logrotate.d (named, e.g. 'msmtp') that configures
logrotate to compress and rotate both the msmtp logs and msmtpq queue
logs.

Suggested contents :
#--------------------------------------------------
/home/xyz/log/msmtp.log /home/xyz/log/msmtp.queue.log {
  rotate 9999
  weekly
  compress
  notifempty
  missingok
}
#--------------------------------------------------

adjust it to your queue and log location(s) and name(s) and
see the logrotate man page for further config information ;
it should be trivial to adapt to other systems

That's it.



msmtp-queue usage :
-----------------

msmtp-queue offers the following options :

  msmtp-queue -r -- runs (flushes) all the contents of the queue

  msmtp-queue -R -- sends selected individual mail(s) in the queue

  msmtp-queue
  msmtp-queue -d -- displays the contents of the queue   (<-- default)

  msmtp-queue -p -- allows the specific purging of one or more mails

  msmtp-queue -a -- purges all mail in the queue

  msmtp-queue -h -- offers a helpful blurt

( msmtp-queue does not log the 'chatter' of user interaction but logs,
  to the queue log, any event that changes the queue in any way )


I find it useful to have a display of the number of mails currently
in the queue in conky ; it uses one shell line (in the .conkyrc script) :

mailq : ${exec /bin/ls -1 ${HOME}/.msmtp.queue/*.mail 2>/dev/null | /usr/bin/wc -l}



With hopes that it's useful,

Chris Gianniotis