4.15.1 The ‘begin’ and ‘end’ special handlers

These two special handlers are executed once for each session, marking its beginning and end. Neither of them takes any arguments:

Handler: begin ¶

# Begin handler
prog begin
do
  …
done

The begin handler is run once for each SMTP session, after the connection has been established but before the first milter handler has been called.

Handler: end ¶

# End handler
prog end
do
  …
done

The end handler is run once for each SMTP session, after all other handlers have finished their work and mailfromd has already returned the resulting status to the MTA and closed connection.

Multiple ‘begin’ and ‘end’ handlers are a useful feature when writing modules (see Modules), because each module can thus have its own initialization and cleanup blocks. Notice, however, that in this case the order in which subsequent ‘begin’ and ‘end’ blocks are executed is not defined. It is only warranted that all ‘begin’ blocks are executed at startup and all ‘end’ blocks are executed at shutdown. It is also warranted that all ‘begin’ and ‘end’ blocks defined within a compilation unit (i.e. a single abstract source file, with all #include and #include_once statements expanded in place) are executed in order of their appearance in the unit.

Due to their special nature, the begin and end blocks impose certain restrictions on the statements that can be used within them:

1. Sendmail actions cannot be used prog end
2. Sendmail macros cannot be used in prog end
3. Header manipulation actions (see header manipulation) cannot be used in ‘end’ handler.

The ‘begin’ handlers are the usual place to put global initialization code to. For example, if you do not want to use DNS caching, you can do it this way:

prog begin
do
  db_set_active("dns", 0)
done

Additionally, you can set up global exception handling routines there. For example, the following ‘begin’ statement installs a handler for all exceptions not handled otherwise that logs the exception along with the stack trace and continues processing the message:

prog begin
do
  catch *
  do
    echo "Caught exception $1: $2"
    stack_trace()
    continue
  done
done