Send a Controlled Request to Postfix with postkick

You will finish with a safe pattern for sending one service-specific request through Postfix's local IPC interface. The examples use postkick from Postfix 3.8.6, installed here as package version 3.8.6-1ubuntu0.1. Allow about fifteen minutes if you already know the Postfix service and request you need to send.

You need a shell, the postfix package, and a local Postfix configuration. This command is an administrative interface, not a general mail submission tool. It does not accept a message body or provide a universal list of requests: the valid request string belongs to the selected service.

1. Confirm the installed command and configuration

Start with read-only checks. They do not need elevated privileges:

$ command -v postkick
/usr/sbin/postkick
$ dpkg-query -W -f='${Package} ${Version}\n' postfix
postfix 3.8.6-1ubuntu0.1
$ postconf -h config_directory
/etc/postfix

The installed manual describes the command as postkick [ -c config_dir ] [ -v ] class service request. A bare invocation is not a status check. It fails because all three positional arguments are required:

$ postkick
postkick: fatal: usage: postkick [-c config_dir] [-v] class service request

Checkpoint: if command -v finds a different binary, or the package version differs, read that machine's manual before relying on the examples below.

2. Identify the endpoint and its access class

The first positional argument is the transport class. Use public for an endpoint accessible by any local user, or private for an administrative endpoint. The second argument is the service name within that class. The installed manual maps these classes to /var/spool/postfix/public and /var/spool/postfix/private.

Do not guess either value. Read the local master.cf and the documentation for the particular service that owns the endpoint. This command does not translate a friendly service description into an IPC request. A request valid for one service can be meaningless to another.

$ config_dir=$(postconf -h config_directory)
$ grep -E '^[[:alnum:]_-]+[[:space:]]+(unix|fifo|pass|unix-dgram)' "$config_dir/master.cf"
# review the local service definitions before choosing SERVICE_NAME

The output is host-specific. Keep the shell variable local to this session and replace SERVICE_NAME only with an endpoint documented by the service you intend to contact.

3. Send the documented request

Once you have confirmed the class, service and request from the service's documentation, use this shape:

$ postkick CLASS SERVICE_NAME REQUEST_STRING

For example, the following is a template rather than a command to run unchanged:

$ postkick public SERVICE_NAME REQUEST_STRING

Keep the request as one shell argument when it contains whitespace. Quote it as a single value:

$ postkick public SERVICE_NAME 'REQUEST STRING WITH SPACES'

Do not copy a request from an unrelated Postfix command and assume it will work here. postkick only provides the local transport. The service decides how to interpret the string and what effect it has.

A successful invocation normally produces no standard output. Capture the status immediately if a script needs to branch:

$ postkick public SERVICE_NAME REQUEST_STRING
$ status=$?
$ printf 'postkick exit status: %s\n' "$status"
postkick exit status: 0

The zero status confirms that the request transaction completed from postkick's point of view. It does not prove that the service performed every later operation you wanted. Check the service's logs or its own status interface as a separate step.

4. Treat private endpoints as an administrative boundary

A private endpoint is not just a different spelling of public. The manual describes private endpoints as administrative access only. Use the least privileged account that is authorised for the service. If that account genuinely needs elevation, put sudo around the complete command and review the request before running it:

$ sudo /usr/sbin/postkick private SERVICE_NAME REQUEST_STRING

This may wake, reload or otherwise affect a running daemon, depending on the service and request. Stop at this checkpoint if you cannot explain the request's effect. There is no generic undo operation in postkick. Recovery belongs to the service: use its documented inverse request, restore its previous configuration, or follow the service's operational recovery procedure.

5. Select another configuration directory

Use -c when the target Postfix instance stores main.cf and related files in a non-default directory:

$ postkick -c /path/to/postfix-config CLASS SERVICE_NAME REQUEST_STRING

The directory must contain the configuration expected by that Postfix instance. Check it before sending anything:

$ test -r /path/to/postfix-config/main.cf && echo 'main.cf is readable'
main.cf is readable

The environment variable MAIL_CONFIG also names the configuration directory, while MAIL_VERBOSE enables verbose logging. Prefer an explicit -c in scripts because the target is visible at the point of use. Do not combine a test configuration with a production socket by accident; confirm the endpoint paths and instance ownership before sending a request.

6. Diagnose a failed transaction

Problems and transactions are written to standard error. First rerun the read-only checks, then inspect the exact command shape:

$ postkick -v CLASS SERVICE_NAME REQUEST_STRING
$ printf 'exit status: %s\n' "$?"
exit status: 0

Use -v for debugging, and add another -v when the installed command supports increasingly verbose logging. A failure commonly means that the class or service socket is absent, the selected configuration points at the wrong queue directory, the user lacks access to a private endpoint, or the request is not valid for that service. The diagnostic text is more useful than treating every non-zero status as a Postfix-wide outage.

Check the relevant paths without changing them:

$ postconf -h queue_directory
/var/spool/postfix
$ ls -ld /var/spool/postfix/private /var/spool/postfix/public

Do not create socket paths, change their ownership, or restart Postfix merely because a guessed request failed. Those are separate operational changes and can disrupt mail handling.