mvmda: MFL hooks
mvmda: MFL hooks
mvmda offers a number of MFL hooks: calls to specifically-named MFL
functions during the execution of mvmda. You (the mvmda user) may
provide these hooks by writing the functions with those specific
names. If the named MFL function does not exist, the hook will not
Hooks should be provided in your personal .mvmdarc file (or the
startup file that's used by mvmda), or in the system-wide mvmda startup
file. Once these startup files have been processed, mvmda will define
some (if not all) of the hooks that are missing, using some generic code
that may or may not be right for you.
List of hooks
These are the list of hooks. Each one is described more fully
further on in this document.
- Assist with handling a delivery error.
- Translate exit code.
- Scan the incoming message after it's been loaded.
Individual hooks are described here. Where formal argument names are
given, they are just examples. You may use whatever argument names you
You may also find examples of some of these hooks along with the
int $hook_delivery_error( string dtype, string ename )
Called after a delivery error, to assist in handling the error.
Formal arguments are:
Very little is done about the error by mvmda outside of this hook,
other than updating error counts. The hook is expected to do the
rest. Significant things the hook should do include:
- dtype: a string containing the delivery type,
one of "store", "pipe", "forward", or "bounce".
- ename: a descriptive name for the error or the error
class. Most error types are not identified by exact name
as there's not a lot of need for that level of distinction at
the MFL level. Instead, the name will be either "soft"
or "hard" for most errors, according to whether mvmda thinks
that the error is likely to be transient or permanent.
The exceptions are:
- "quota": An over-quota condition occured.
- Decide about rejection.
- If there's a delivery error, perhaps somebody wants to know about
it. This hook can request a notification by calling the $msg_reject
built-in MFL function (documented elsewhere). Be sure to read the
caveats about using $msg_reject, particularly the distinction between
SMTP-time and non-SMTP-time rejections.
- Permit or inhibit annotation.
- A normal thing to do is for mvmda to annotate the current message
with some text describing the error that happened. This will be seen
if the message ends up being delivered to some destination after the
delivery attempt that caused this error; it may also be seen by any
bounce/reject that happens later. This hook controls this by its
Return value: This hook should return 0 (false) to
inhibit error message annotation, or non-zero (true) to proceed with
annotation as normal.
int $hook_exitcode( int intcode )
Called when mvmda is about to exit, this hook may be supplied to translate
the exit code to something you'd rather see.
mvmda has just a few exit codes- a simple value can not really
encapsulate the completion status of a program that may have handled
mail in a variety of ways. Note that mfl defines some mfl-preprocessor
constants for exit codes that are used by all mvmf applications; mvmda
uses some of these, as follows:
- $MEX_OK -- good status.
- This value (probably 0) indicates that mvmda thinks that everything
went just fine.
- $MEX_SOFT -- soft error.
- A soft error
- $MEX_HARD -- hard failure.
- Some hard failure.
- $MEX_OKCONT -- ok but not completely handled.
- mvmda will use this exit code to indicate that it has
done its job OK, but that the message is probably not completely
handled. This is useful in a pipeline mode, when mvmda
is expected to do some processing of a message but where there are
still some extra steps to be done later.
Called after mvmda has opened and scanned the incoming message, to
pick out anything that might be needed. No arguments are passed.
Significant things that this hook might do include:
- Scan the header for responsible IP addresses.
- MFL has some functions to check IP addresses against DNSBL
databases. mvmda must be told what IP addresses are significant
in the message, i.e. which IP addresses are testable. This
hook should pick those IP addresses out of the header and
add them to the responsible IP list (e.g. by calling the
$msg_rip_add() built-in MFL function.
Return value: This function is defined as returning an
int value, but mvmda ignores any value returned. Return 0 to be safe.