GreenArrow Email Software Documentation

SimpleMH Config File

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
$CLICKTHROUGH_URL = "http://www.example.com/click";

# 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
$RETURN_PATH_OVERRIDE = undef;
#$RETURN_PATH_OVERRIDE = 'return-%%VERP%%@example.com';

# 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

The default setting is http://www.example.com/click. If you plan to use SimpleMH’s Click + Open and/or Unsubscribe Tracking you should replace the domain name portion of this configuration option with a URL Domain.

If GreenArrow Technical Support is handling your installation then you can expect the Primary Server Domain to be used here.

If you’re doing the Installation on your own then you’ll need to make sure to set up a URL Domain and add that URL Domain in this configuration.

$RETURN_PATH_OVERRIDE

The default configuration here does not have a Return-Path / Bounce Address configured, so if you plan to use GreenArrow’s Bounce Processing you need to update this configuration.

If GreenArrow Technical Support is handling your installation then you can expect the Primary Server Domain to be used here.

If you’re doing the Installation on your own then you’ll need to make sure to set up a Bounce Address / Return-Path Domain and add that Bounce Address in this configuration.

Note that this configuration requires a certain syntax in order to work with GreenArrow’s VERP Encoding. Use the commented example in the default config to make sure you set this correctly (replacing example.com with your own bounce address domain):

$RETURN_PATH_OVERRIDE = 'return-%%VERP%%@example.com';

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 this file is missing or blank, the default value of 5 processes will be used.

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.

 Bad Address Suppression
Logging all SimpleMH Messages 

Copyright © 2012–2023 GreenArrow Email