USING mvmda, the mail delivery agent.

mvmda operates on a mail message, referred to as the incoming message.
To process the message, it uses its own scripting language called MFL
which is a combination of C-like constructs and the IETF "Sieve" mail
filtering language.

Much of mvmda's operation and flow is dictated by a system-wide MFL
script.  If you are reading this, you are probably installing mvmda, and
you get to decide what that script does.  If you aren't the installer,
you can still find the path to the system-wide RC file and read it
to see what it does.  (Use the -VV option of mvmda).

The system-wide rc script is likely to hand control off to one or
more script files that you (the user) supplies.  Your script files
are likely either specified directly on the command line, or given
a default name (or some combination of the two).

Check the 'files' area for some sample system-wide rc script(s).



INVOKING MVMDA

In a nutshell, you arrange to feed an incoming message into mvmda on
its stdin, supplying some command line arguments and perhaps identifying
script file(s) to apply to the message.  (How the script files are
chosen depends on the system-wide script, as mentioned above.  However
without going on about that every time it's mentioned, we'll assume here
the rc script interprets the command line arguments as script file names.)

mvmda is happiest if the incoming message is an actual file that it can
seek into so that the same message may be scanned more than once.  If it
can't seek into the input message (e.g. if it's piped into, a la from
procmail), it will gamely record to a tempfile what it can't cache in
memory and obtain multiple accesses to the message that way.

You can use a .forward file, a line in a procmail recipe, or a .qmail
control file, or a sendmail mailer definition.  I'll bet you can also use a
postfix or exim mailer definition too, but I don't have guides for that
yet.

Using .forward files and procmail recipes:

Assuming mvmda is in "/bindir" and you are giving it (fake for examples)
arguments "-a -b -c" and pointing it at a script "x.mfl" , the following are
some examples.  (There may be mistakes, but I'll assume you are familiar
enough with your own environment to spot them.  But let me know...)

Sendmail .forward file contents:
"|/bindir/mvmda -a -b -c x.mfl"

Postfix .forward file contents:
|"/bindir/mvmda -a -b -c $HOME/x.mfl"

qmail .forward file contents (assuming 'dotforward' is in use):
"|/bindir/mvmda -a -b -c $HOME/x.mfl"

qmail .qmail file contents:
|/bindir/mvmda -a -b -c $HOME/x.mfl

procmail recipe:
:0
| /bindir/mvmda -a -b -c $HOME/x.mfl

(See the 'files' area for using sendmail mailer definitions).

As for the command line arguments (instead of "-a -b -c"):

There's a man page that describes them.  (mvmda/mvmda.1). Briefly:

  -d user
     if you want or need to tell mvmda what user is being delivered
     to.  mvmda must either be running as the specified user or as root,
     in which case it will attempt to become that user.

  -m is the default folder name.  This is the folder name that is used
     by sieve's "keep" or "implicit keep" (and is therefore the folder that
     is filed into if no other explicit action is taken on a message).
     If you don't supply this, the name "INBOX" is used.

  -q if it's being executed out of a .qmail file (and you've enabled
     QMAIL support when you configured mvmf).  This is important to
     access envelope information.

When your mfl script writes to a mail folder, the folder name must refer to
an existing namespace.  Namespaces are defined by MFL code, and it's likely
that the system-wide startup script has defined common ones for your use.
Each namespace is identified by a prefix; the folder name is compared to
each namespace's prefix until there is an initial substring match, with the
longest match winning.  As a trivial example, you might have a namespace
called "MyFolders/" which maps to a "Mail" subdirectory in your home
directory.  If your script writes to a folder "Myfolders/work" then the
folder would be place into a folder "work" in your "Mail" subdirectory.

See the NAMESPACES file for more.



SCRIPTS

Scripts are harder to describe, especially without any included
documentation.  Probably it's just easiest to point you to the mvmf
page, where there is extensive documentation and a number of
examples.  Have a look at the examples first (to get a feel for it),
then the language document, and then perhaps the SIEVE RFCs and I-Ds.
The mvmf page is at:

    http://www.mvmf.org/

There are also a couple of examples in the "files" directory in the
mvmf source tree.

Use "-c" to do a basic syntax check:

   mvmda -c x.mfl

Note that it is possible for the syntax check to pass but the script
to fail execution.  (e.g. if a "require" isn't met.)

Send feedback to me (mem@mv.com) directly please.

-mm-			20040101/20070108		mem@geezer.org
						or	mem@mvmf.org