Skip to content

Latest commit

 

History

History
139 lines (99 loc) · 4.62 KB

INSTALL.en.md

File metadata and controls

139 lines (99 loc) · 4.62 KB

Non-delivery reports (bounces) collector

This collector is desined to assemble email bounces from Exim MTA in order to analyse non-existent/invalid recepient email addresses.

Parses Exim headers and builds a table with fields:

  • Date and time of the letter (Delivery-Date header)
  • Sender address (Envelope-To header)
  • Recipient address (X-Failed-Recipients header)
  • Description of the error (as it is generated by the recipient's server)

System requirements

  • MariaDB 10.6+ or MySQL 5.7+
  • PHP 8.1+ (with imap and pdo_mysql extensions)
  • Any HTTP server with PHP support
  • IMAP server with Exim4 bounces box

Building of the program

To build, run make, the output is the bounceman.phar file, which is both a console program and a web application.

Typical use case

It must be used a real IMAP-enabled mailbox to collect non-delivery reports (bounce or Mailer Daemon messages). The mailing software must be configured to use this mailbox for the Return-Path address.

  • Primary DB initialisation with the init command
  • Adding boxes with the new command
  • Enabling boxes with the enable command
  • Adding the collect command to the crontab
  • Using the check and dump commands or HTTP API

Console commands

Console commands are run like this: php bounceman.phar COMMAND.

The --since and --until options accept date/time in the format described here.

help	- short cli reference

init	- database initialisation, run before use

new	- adding a mailbox for collect bounces

edit	- mailbox setting editing

list	- list of configured mailboxes

collect	- collect messages from all enabled mailboxes

enable MBOX	- enable a mailbox named MBOX

disable MBOX	- disable a mailbox named MBOX

test MBOX	- test IMAP connection to a mailbox named MBOX

delete MBOX	- deleting a mailbox named MBOX

check [OPTIONS] [EMAIL]...	- search for a failed recipient email address in the list of bounce hits
	OPTIONS:
		--since	- date/time of the search time interval beginning
		--until	- date/time of the search time interval ending
		--mbox	- the name of mailbox wich to search,
			the option can be repeated to specify multiple mailboxes;
			by default, the search is performed in all mailboxes
	EMAIL -	the desired email address, it is possible to specify several

dump [OPTIONS] [MBOX]...	- list of all email addresses from the list of undelivered
	OPTIONS:
		--since	- date/time of the search time interval beginning
		--until	- date/time of the search time interval ending
	MBOX	- the name of the mailbox in which to search,
		it is possible to specify several;
		by default, the search is performed in all mailboxes

Web interface

The web interface requires any HTTP server with PHP support.

An example of starting a server built into PHP: php -S 127.0.0.1:8080 bounceman.phar, after that the web intercface can be available at http://localhost:8080/.

It is recommended to use PHP-FPM daemon with this application. Configuration example for Nginx (with PHP-FPM):

server {
    listen 80;
    server_name bounceman.local;

    location / {
        fastcgi_pass unix:/path/to/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME /path/to/bounceman.phar;
        include fastcgi_params;
    }
}

HTTP API

In addition to the web interface, an HTTP API is available All parameters are passed using the GET method. The since and until options are the same tas the --since and --until options for console commands.

/check - search for a failed recipient email address in the list of bounce hits
	Options:
		since		- date/time of the search time interval beginning
		until		- date/time of the search time interval ending
		mboxes[]	- the name of mailboxes wich to search;
				by default, the search is performed in all mailboxes
		emails[]	- the desired email addresses
	JSON response:
		Array of objects with fields:
			email		- desired email address
			status		- OK (not found), ERROR (found)
			mbox		- the mailbox in which the email address was found 
			date		- date and time of the last undelivered email
			error		- error text of the last undelivered email
/dump - list of all email addresses from the list of undelivered
	Options:
		since		- date/time of the search time interval beginning
		until		- date/time of the search time interval ending
		mboxes[]	- the name of mailboxes wich to search;
				by default, the search is performed in all mailboxes
	Plain tenx response:
		Each line contains one email address for which there is an undelivered email