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 be called.

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.

$hook_delivery_error: Assist with handling a delivery error.
$hook_exitcode: Translate exit code.
$hook_msg_read_after: Scan the incoming message after it's been loaded.

The hooks

Individual hooks are described here. Where formal argument names are given, they are just examples. You may use whatever argument names you wish.

You may also find examples of some of these hooks along with the mvmf distribution.

int $hook_delivery_error( string dtype, string ename )

Called after a delivery error, to assist in handling the error. Formal arguments are:

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.

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:

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.

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.

int $hook_msg_read_after()

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.