GreenArrow Documentation

Event Notification System Configuration

Here are the steps to follow when configuring the Event Notification System:

  1. If you’re using Studio, then start logging the desired Studio events.

  2. If you’re sending any non-Studio mail, then start logging the desired non-Studio events. You can control which types of events get logged by creating one or more of the following configuration files within the /var/hvmail/control/ directory:

    • record_events.simplemh.scomp - SimpleMH and Raw Injection scomp (spam complaint) events
    • record_events.simplemh.bounce_all - SimpleMH and Raw Injection bounce_all events
    • record_events.simplemh.bounce_bad_address - SimpleMH and Raw Injection bounce_bad_address events
    • record_events.simplemh.unsub - SimpleMH engine_unsub (unsubscribe) events
    • - SimpleMH open events
    • - SimpleMH click events

    See the Types of Events page for more details on any of the above event types.

    Each file should have its contents set equal to 1 if you wish to log its event type. For example, to log all non-Studio event types, run:

    cd /var/hvmail/control/
    echo 1 > record_events.simplemh.scomp
    echo 1 > record_events.simplemh.bounce_all
    echo 1 > record_events.simplemh.bounce_bad_address
    echo 1 > record_events.simplemh.unsub
    echo 1 >
    echo 1 >

    Each file should have its contents set equal to 0 if you do not wish to log its event type. For example, to stop logging all non-Studio event types, run:

    cd /var/hvmail/control/
    echo 0 > record_events.simplemh.scomp
    echo 0 > record_events.simplemh.bounce_all
    echo 0 > record_events.simplemh.bounce_bad_address
    echo 0 > record_events.simplemh.unsub
    echo 0 >
    echo 0 >

  3. If you’re sending mail using SimpleMH, and would like the User Agent string to be logged to the user_agent field for clicks and opens, then set the opt.simplemh_tracking_include_user_agent file equal to 1:

    echo 1 > /var/hvmail/control/opt.simplemh_tracking_include_user_agent

    This can be disabled at anytime by setting this file equal to 0:

    echo 0 > /var/hvmail/control/opt.simplemh_tracking_include_user_agent

  4. The creation of Delivery Attempt events is disabled by default. If you would like to keep these events disabled, then move onto the next step.

    If you would like to enable Delivery Attempt events, then edit the /var/hvmail/control/record_events.delivery_attempt.json configuration file. The file consists of a JSON object which defines the desired configuration. Here are the default settings:

      "enabled": false,
      "include_status": {
        "success":         true,
        "deferral":        false,
        "failure":         true,
        "failure_toolong": true,
        "connmaxout":      false
      "include_first_attempt_regardless_of_status": true,
      "include_local_channel": false

    Here’s the meaning of each setting:

    • enabled - if true, then delivery attempt event creation is enabled.

    • include_status - a JSON object containing a series of boolean keys that specify which types of delivery attempts should create events. deferral and connmaxout delivery attempts do not trigger events by default because it is possible for there to be many deferral and connmaxout delivery attempts for each message due to delivery retries. Creating events for each of these could consume significant server resources and slow down message processing. With the default settings, each message will have a single success, failure or failure_toolong event.

    • include_first_attempt_regardless_of_status - if true then the first delivery attempt for a message (where is_retry is 0) should always have an event created regardless of the status. This is useful because the first delivery informs that a new message has been created.

    • include_local_channel - if true then delivery attempts to local domain names (incoming email domains) will have events created. If false, they will be excluded. Most of the deliveries to local domains are bounce messages received through SMTP and internally created bounce messages.

    When you’re finished making your changes, run the following command to verify that there are no syntax errors:

    /var/hvmail/bin/hvmail_logwriter --check-config-event

    The configuration file is automatically re-read every few seconds, so there is no need to restart any services in order to apply changes to it.

  5. Configure the receiving end of your desired Event Delivery Method(s).

  6. Turn off the Event Processor:

    svc -d /service/hvmail-event-processor

  7. Configure the Event Processor to use your desired Event Delivery Method(s).

  8. Turn on the Event Processor:

    svc -u /service/hvmail-event-processor

  9. Review the Event Processor’s log for errors:

    tail -F /var/hvmail/log/event-processor/current | tai64nlocal