GreenArrow Email Software Documentation

Delivery Attempt Log (Deprecated)

Deprecation Notice

The Delivery Attempt Log has been deprecated as of GreenArrow v4.285.0. Please see the event_delivery_logfile and event_delivery_pipe_command configuration directives instead.


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,
  "pipe_command": "",
  "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:



If true, then delivery attempt logging is enabled.



The filename to write to. Either this setting or pipe_command is required if enabled is true. The file will be opened for appending by the root user.



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.



An optional command to which to open and write the log. Either this setting or filename is required if enabled is true.

This command is executed and closed for each batch (approximately every 3 seconds). The program must exit successfuly (return status 0) or else it will be retried. If the program exits non-success (a return status other than 0, or if it is killed by a signal), there may be some duplicate delivery log lines and writing to filename will be prevented or delayed.

This program is run by the root user. The log data is written to the program’s STDIN. The program should read all of STDIN and encounter an EOF before exiting.



The format of logfile data to write. Options are:



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.



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.



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":1641480948.07533,"channel":"remote","status":"success","is_retry":0,"msguid":"1641480947.54314359","recipient":"[email protected]","sender":"[email protected]@[]","mtaid":"2","sendid":"default220106","listid":"t1","injected_time":1641480947,"message":" accepted message./Remote host said: 250 2.0.0 OK  1641480948 bi10si877913qkb.210 - gsmtp/","outmtaid":"2","outmtaid_ip":"","outmtaid_hostname":"localhost","sendsliceid":"","throttleid":null,"clicktrackingid":"","mx_hostname":"","mx_ip":"","from_address":"[email protected]","headers":{"Subject":["This is a test of the subject"]}}

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

timestamp=<1641481093.03894> channel=<remote> status=<success> is_retry=<0> msguid=<1641481092.90011942> recipient=<[email protected]> sender=<[email protected]@[]> MTAid=<2> SendID=<default220106> ListID=<t1> injected_time=<1641481092> message=< accepted message./Remote host said: 250 2.0.0 OK  1641481093 x16si812070qko.519 - gsmtp/> outmtaid=<2> SendSliceID=<> throttleid=<> clicktrackingid=<> mx_hostname=<> mx_ip=<> from_address=<[email protected]> headers=<{"Subject":["This is a test of the subject"]}>

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–2024 GreenArrow Email