To register a handler, run the following command:

# ./mail_handlers_control --add
                --priority=<number>
                --name=<handler name>
                --mailname=<mailname>
                --queue=<before-local|before-remote|before-queue|before-data>
                --type=<sender|recipient|sender-domain|recipient-domain|global>
                --executable=<executable file>
                [ --context=<context> ]
                [ --enabled ]

The arguments are explained in the following table.

Argument Definition
--name Specifies the handler name. The string is allowed to contain any character allowed in UNIX file name (that is, anything except slash and NUL). Registration will fail if a handler with the specified name has already been registered.
--type

Specifies the type of a handler, may take the following values:

  • global handler is called for all messages.
  • sender-domain handler is called for messages whenever the domain part of the sender address matches the specified domain
  • recipient-domain handler is called for messages whenever the domain part of one of the recipient addresses matches the specified domain
  • sender handler is called for messages whenever the sender address matches the specified address
  • recipient handler is called for messages whenever any of the recipient addresses matches the specified address

--mailname

Specifies a domain or a mail address for the handler-type.

Not required if the handler type is global.
--priority Specifies the hook priority in the queue of hooks.
--executable

Specifies the handler executable file.

Registration will fail if the file does not exist.
--context Specifies the context. This is an opaque string to be passed to the handler on the command line.
--enabled Specifies whether to enable the handler.
--queue

Specifies the hooking point. Should be one of: before-queue, before-local, before-remote, before-data.

See Hooking Points for details.

The following handler is added to filter correspondence before local delivery:

# ./mail_handlers_control --add
    --name=1my_handler-ld
    --type=sender
    --mailname=myema@example.com
    --executable=/usr/local/bin/my_handler.sh
    --context='context'
    --queue=before-local
    --priority=33
    --enabled