GreenArrow Email Software Documentation

Delivery Attempt Log


GreenArrow can be configured to log delivery attempts to a logfile. There are a number of configuration options available, including whether to enable this logging and what format to log the data in.


There are two alternative ways to monitor delivery attempts:

  1. Use hvmail_report to request data for a particular time period.

  2. Use the Event Notification System’s delivery_attempt event type.


Delivery attempt logging is disabled by default. To enable it, and optionally adjust other settings, edit the /var/hvmail/control/delivery_attempt_logfile.json configuration file.

This file is written in JSON. You can verify that there are no syntax errors in your edits by running:

hvmail_logwriter --check-config-file

The configuration file is automatically re-read every few seconds, so no services need to be restarted to apply changes.

Here are the default settings:

  "enabled": false,
  "filename": "",
  "filename_append_date": false,
  "format": "json",
  "include_status": {
    "success":         true,
    "deferral":        true,
    "failure":         true,
    "failure_toolong": true,
    "connmaxout":      false
  "include_first_attempt_regardless_of_status": true,
  "include_local_channel": true

Here’s the meaning of each setting:

  • enabled - if true, then delivery attempt logging is enabled.

  • filename - the filename to write to. This is required if enabled is true. The file will be opened for appending by the root user.

  • filename_append_date - if true, then a period and the date in YYYY-MM-DD format will be appended to the filename. For example /tmp/file becomes /tmp/file.2017-03-21. When the first delivery attempt is logged for the next day, it will be written to /tmp/file.2017-03-22.

  • format - the format of logfile data to write. Options are:
  • include_status - a JSON object containing a series of boolean keys that specify which types of delivery attempts should be logged. With the default settings, each message will either have a single success, failure or failure_toolong log entry.

  • include_first_attempt_regardless_of_status - if true then the first delivery attempt for a message (where is_retry is 0) should always have a log entry 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.


Here’s an example log entry that uses json formatting:

{"timestamp":1586783093.08601,"channel":"remote","status":"success","is_retry":0,"msguid":"1586783092.8086183","recipient":"[email protected]","sender":"[email protected]","mtaid":"","sendid":"","listid":"","injected_time":1586783092,"message":" accepted message./Remote host said: 250 2.0.0 OK  1586783093 bb2si5606222qvb.26 - gsmtp/","outmtaid":"2","outmtaid_ip":"","outmtaid_hostname":"","sendsliceid":"","throttleid":null,"clicktrackingid":"","mx_hostname":"","mx_ip":""}

The following keys are populated in the json format, but not the processed or human format:

  • outmtaid_ip - the IP address GreenArrow used while attempting to deliver the message.
  • outmtaid_hostname - the hostname of the IP address that GreenArrow used while attempting to deliver the message.

All other keys in the above example are also in the Delivery Event Processed Logfile Format and described in its documentation.

Log Rotation

GreenArrow does not rotate delivery attempt logs. If you enable delivery attempt logging, then you must set up your own log file rotation system in order to avoid running out of disk space.

The logfile is re-opened for appending every few seconds, so no services need to be restarted for the logfile to be re-created after being moved or deleted.

Copyright © 2012–2021 GreenArrow Email