SimpleMH Config File

Table of Contents
Editing the Config File
Configuration Definitions
Default Configurations
SimpleMH Concurrency

GreenArrow’s SimpleMH feature is mostly managed via the Mail Class configurations in the web interface. However, some base configurations are managed in the command line configuration. This document covers the key components of this config file that customers may need to manage over the course of installing or configuring their license of GreenArrow.

Editing the Config File

The command line configuration file for SimpleMH is located in:

/var/hvmail/control/simplemh-config

This is a text file that can be edited with your favorite command line editor.

Syntax errors introduced in this file can break SimpleMH in ways that are not going to be obvious, so it is critical that you verify the syntax of this file after each edit by running this command:

/var/hvmail/libexec/perl -c /var/hvmail/control/simplemh-config

If everything is correct you should get this response:

/var/hvmail/control/simplemh-config syntax OK

Configuration Definitions

There are some configuration options in this file that are outside the scope of this document. The options covered here are the ones that are most commonly used by anyone sending using SimpleMH. If you see configurations that you are unsure about or would like to have documented, please contact GreenArrow Technical Support.

Here are the configuration options covered in this document:

$BAD_ADDRESS_REMOVE: enable or disable Bad Address Suppression.
$DEFAULT_MAILCLASS: the Mail Class to use when a message gets injected using SimpleMH, but without specifying a Mail Class.
$CLICKTHROUGH_URL: the URL Domain used by default in a Mail Class when an alternate is not defined.
$RETURN_PATH_OVERRIDE: the Bounce Address / Return-Path Address used by default in a Mail Class when an alternate is not defined.

Other configurations in this file that are not covered in this document:

$MAILCLASS_INFO: this field can be used to define Mail Classes used by SimpleMH. (Deprecated by the web interface Mail Class Configuration.)
$TIME_ZONE_OFFSET: the time zone offset SimpleMH uses (for things like automatically setting a new Instance ID each day). While this configuration field still works, we recommend that you set this to undef and instead use the engine_time_zone configuration directive.
$CUTOFF_HOUR: the hour SimpleMH uses as the cutoff when setting a new Instance ID each day.
$BAD_ADDRESS_DEV_NULL_DOMAIN: the domain SimpleMH uses when rewriting the email address in Bad Address Suppression. The default value is a special domain that will accept and discard all emails, so this should not be modified without careful consideration.
$CAMPAIGNID_PREFIX: the prefix used with GreenArrow Monitor. This value is set for you when you purchase a Monitor subscription so it should not be modified unless you’re instructed to do so by GreenArrow Technical Support.
$SENDER_HEADER_OVERRIDE: the email address used when overwriting the original Sender: header address.
$DO_NOT_OVERRIDE_SENDER_IF_FROM_MATCHES_THIS_REGEX: a configuration that can define when to disable the $SENDER_HEADER_OVERRIDE feature.

Default Configurations

Here is GreenArrow’s default SimpleMH configuration:

#                                                                                       do clickthrough tracking?
#                                                                    seeding   seeding  |    number of messages to archive
#        mail class             listid  mtaid                 seed?  start     end      |    |      dkim selector
#        ----------             ------  -------------------   -----  -------   -------  ---  -----  -------------

$MAILCLASS_INFO = {
};

# offset for time zone in hours (get from running 'date --rfc-822')
$TIME_ZONE_OFFSET = undef; # prefer to use configuration directive engine_time_zone

# cutoff hours between days; 0=12:00am, 6=6:00am
$CUTOFF_HOUR = 0;       # 12:00am

# if we should remove bad addresses from the sending
$BAD_ADDRESS_REMOVE = 0;

# domain to rewrite bad addresses to (all addresses at this domain should go to /dev/null)
$BAD_ADDRESS_DEV_NULL_DOMAIN = "badaddress.discardallmail.drh.net";

# mailclass to use if no mailclass is specified (if undef, do nothing if no mailclass is specified)
$DEFAULT_MAILCLASS = "default";

# url to use for clickthrough tracking
# !!! This is the legacy way to set a default URL domain.
$CLICKTHROUGH_URL = undef;

# return path prefix for the campaign ID (campaign ID is produced by taking this and adding the seconds since epoch)
$CAMPAIGNID_PREFIX = "fsasyadrh";

# Override the return path on all outgoing messages to this value (or don't, if undef)
# %%LISTID%% replaces with the listid
# %%SENDID%% replaces with the sendid
# !!! This is the legacy way to set a default bounce mailbox.
$RETURN_PATH_OVERRIDE = undef;

# Add this sender header (undef not to override)
$SENDER_HEADER_OVERRIDE = undef;
#$SENDER_HEADER_OVERRIDE = '[email protected]';

# Do not add the sender header if the From header matches this regex
$DO_NOT_OVERRIDE_SENDER_IF_FROM_MATCHES_THIS_REGEX = undef;
#$DO_NOT_OVERRIDE_SENDER_IF_FROM_MATCHES_THIS_REGEX = '@example.com';

Many of SimpleMH’s key features are disabled by default.

`$BAD_ADDRESS_REMOVE`

SimpleMH Bad Address Suppression is disabled by default. To enable this, change the 0 to a 1.

`$DEFAULT_MAILCLASS`

The Mail Class defined here by default is named default. You do not have to use this Mail Class as the default configuration, but the Mail Class you have defined here must exist in GreenArrow’s Mail Class configuration.

If GreenArrow Technical Support is handling the installation for you, we will set up this Mail Class for you.

If you’re doing the Installation on your own then you’ll need to make sure to create a Mail Class with a name that matches the value you put in the $DEFAULT_MAILCLASS config.

`$CLICKTHROUGH_URL`

This setting has been deprecated.

In its place, use one of the following options:

If you configure URL domains in the configuration file (define_url_domains_in_config_file), use the directive default_url_domain.
Otherwise, you can set this value in either the user interface on the URL Domains screen or via the API.

If $CLICKTHROUGH_URL is configured to any value except undef, it will take precedence over the preferred way to configure the default URL domain.

`$RETURN_PATH_OVERRIDE`

This setting has been deprecated.

In its place, use one of the following options:

If you configure Incoming Email Domains in the configuration file (define_incoming_email_domains_in_config_file), use the directive default_bounce_mailbox.
Otherwise, you can set this value in either the user interface on the Incoming Email Domains screen or via the API.

If $RETURN_PATH_OVERRIDE is configured to any value except undef, it will take precedence over the preferred way to configure the default bounce mailbox.

SimpleMH Concurrency

The configuration file /var/hvmail/control/opt.simplemh.redis_num_workers defines the number of concurrent UNIX processes that will handle SimpleMH email sent through the HTTP API.

If not defined in the config file, in configuration then SimpleMH Concurrency will be set to:

the smaller of either:
- the number of CPUs × 2, or
- the GB of memory × 2
regardless of the above:
- it will always be set to at least 5, and
- it will be set to at most 1024

If defined in the config file:

If the value within this file is less than 1, 1 process will be used.
If the value within this file is over 1024, 1024 processes will be used.

After editing this file, run svc -t /service/hvmail-simplemh2 to load the new setting.