Configuration Hooks

• Table of Contents
• Introduction
• Hook Definition
  • Return a subroutine
  • Importing packages
  • Subroutine input and output
• Available Hooks
  • simplemh_default_mailclass
  • simplemh_early_modify_message
  • simplemh_modify_message

Introduction

Configuration Hooks provide ways to add custom code to various parts of GreenArrow. This page details all supported hooks that can be added to GreenArrow via the define_hook configuration directive.

Hook Definition

Return a subroutine

User-defined hooks are expected to return a subroutine reference. This is because the hook is executed once to obtain the subroutine reference, then the (cached) subroutine is called each time the hook needs to be called. This is a performance advantage over parsing and evaluating the hook each time it needs to be called.

Here’s an example of what this looks like:

define_hook simplemh_early_modify_message perl <<HOOK
    return sub {
        my $input = shift;

        return {
            body => "Everything I email is just this one message. Boring!\n";
        };
    };
HOOK

Importing packages

When importing external packages (e.g. the JSON package), it’s important that the use statement be done outside of the returned subroutine, so that the package is only imported a single time.

Subroutine input and output

The subroutine returned by a hook should itself exhibit the following behaviors:

• It should accept a single parameter as input, which will be a hash. The definition of this input hash is specified for each hook in the “Input” section.

• It should return either the null value undef or a hash reference value { ... }. The definition of this output hash is specified for each hook in the “Output” section.

Available Hooks

simplemh_default_mailclass

This hook is executed when SimpleMH cannot otherwise determine the mail class to use for a message (for example from the X-GreenArrow-MailClass header).

If both simplemh_default_mailclass and this hook are configured, this hook takes precedence over it. If this hook returns a null value or a blank string, then simplemh_default_mailclass will be used.

This hook is called after simplemh_early_modify_message.

define_hook simplemh_default_mailclass perl <<HOOK
    return sub {
        my $input = shift;

        # Look for our custom X-MTA-MailClass header, and use the mailclass found within.
        if ( $input->{headers} =~ m{^x-mta-mailclass: (.*)\n}i ) {
            return { mailclass => $1 };
        }

        return undef;
    };
HOOK

simplemh_early_modify_message

This hook is executed when SimpleMH begins processing a message. This hook is evaluated prior to X-GreenArrow-* headers being processed. As such, this can be useful for adding or modifying X-GreenArrow-* headers to the message.

define_hook simplemh_early_modify_message perl <<HOOK
    return sub {
        my $input = shift;

        my $now = POSIX::strftime("%Y-%m-%d", gmtime(time()));
        my $body = $input->{body};

        # Replace %%date%% with the current UTC date.
        $body =~ s{%%date%%}{$now}gi;

        return { body => $body };
    };
HOOK

simplemh_modify_message

This hook is executed while SimpleMH is processing a message. By the time this hooks is evaluted, SimpleMH has already processed and removed the X-GreenArrow-* headers, but has not yet done the following: Click and open tracking, Sending to a seed list, Message archiving.

define_hook simplemh_modify_message perl <<HOOK
    # Import the JSON package; it's important that imports be done OUTSIDE of the
    # returned subroutine, so that it only happens once.

    use JSON;

    return sub {
        my $input = shift;

        # Prepend an X-Metadata header with a JSON document.
        return {
            headers => sprintf("X-Metadata: %s\n%s",
                JSON::encode_json({
                    time_injected => time(),
                }),
                $input->{headers},
            ),
        };
    };
HOOK