
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 by exporting these environment variables

  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 MSMTPQ_RC var to point to the location of the config file
    (if unset, will look at $XDG_CONFIG_HOME/msmtpq/config, then ~/.msmtpqrc)
  set the MSMTPQ_Q var to point to the location of the queue directory
  set the MSMTPQ_LOG var to point to the location of the queue log
  set the MSMTPQ_LOG_DATEFMT var to the date format to use for the logs
    (for backwards compatibility: %Y %d %b %H:%M:%S
                         ISO8601: %Y-%m-%dT%H:%M:%S%:z
    )

you can put this variables into a config file msmtpq is considering now ;
see as example:
cat << EOF > ~/.msmtpqrc
MSMTPQ_Q=~/.msmtp.queue
MSMTPQ_LOG=~/log/msmtp.queue.log
EOF

Or for a more XDG-style configuration:
cat << EOF > $XDG_CONFIG_HOME/msmtpq/config
MSMTPQ_Q=$XDG_STATE_HOME/msmtpq/queue/
MSMTPQ_LOG=$XDG_STATE_HOME/log/msmtp.queue.log
EOF

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 MSMTPQ_Q variable should have the location of the queue directory ;
please note that it's preferable to create the queue directory (with
0700 permissions) before using these routines ; the Q variable is a
deprecated alias of MSMTPQ_Q

the MSMTPQ_LOG variable should have the desired name & location of the
queue log ; set it to an empty string (export MSMTPQ_LOG="") to disable
logging ; the LOG variable is a deprecated alias of MSMTPQ_LOG

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 setting LOG to an empty string -
export 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 three methods of setting options -

- set the vars in a config file

  see the explanation on MSMTPQ_RC -- the selected file will be sourced if it
  exists

- 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. note variables will be overridden by config file values unless this is
  unset (eg by invoking msmtpq using env -u MSMTPQ_RC msmtpq, or by setting
  MSMTPQ_RC=/dev/null)

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=c /path/to/msmtpq"
                 # use queue with curl connection test
                 # (curl 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_CONN_TEST=q /path/to/msmtpq"
                 # forces to queue all emails

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
