Using the kcli Command-Line Client
KumoMTA comes with several API endpoints to make administration of the server
easier for common tasks, and additionally comes with the
command-line client which provides access to the APIs for local administrative
kcli client is located at
/opt/kumomta/sbin/kcli and requires a
configured HTTP Listener to function.
At minimum, the
kcli client must be passed an endpoint and a command:
--endpoint parameter indicates the HTTP API endpoint you have configured
for your KumoMTA instance. This documentation uses
because that endpoint is shown as a suggested default for that http
listener. You need to adjust it to match whatever you have configured for
your HTTP listener in your environment.
Since: Version 2023.08.22-4d895015
The functionality described in this outlined box requires version 2023.08.22-4d895015 of KumoMTA, or a more recent version.
--endpoint defaults to
http://127.0.0.1:8000 and can be omitted.
KUMO_KCLI_ENDPOINT is set in the environment, its value will be used
--endpoint is not specified.
In earlier versions, you need to explicitly pass
kcli client can be used to administratively bounce messages currently
queued in the server with the following format:
Allowed arguments for the bounce command include:
Optional string. The domain name to match. If omitted, any domain will match.
Optional string. The campaign name to match. If omitted, any campaign will match.
Optional string. The tenant to match. If omitted, any tenant will match.
If you specify none of
ALL queues will be bounced.
With great power, comes great responsibility!
Required. Reason to log in the delivery log.
Optional duration string. Defaults to
Specifies how long this bounce directive remains active.
While active, newly injected messages that match the bounce criteria will also be bounced.
See the Bounce API page of the Reference Manual for more information.
Listing Current Bounces
You can list the currently active bounce commands with the following command:
See the Admin Bounce List API page of the Reference Manual for more information.
Removing a Bounce
Because bounce commands default to a five-minute duration, messages will continue to bounce after the command has been issued. This helps with scenarios such as when a campaign needs to be aborted, but the entire campaign may not have been injected at the time the command was issued.
Sometimes after a bounce has been issued there is a need to cancel the bounce
before the time window has expired. Once a bounce command's ID is determined
bounce-list command, the bounce can be canceled with the
See the Bounce Cancel API page of the Reference Manual for more information.
Setting The Diagnostic Log Level
While the log level is typically set in your configuration, it can also be set
on an ad-hoc basis using the set-log-filter command in
See the Set Diagnostic Log Filter page of the Reference Manual for more information.
Monitoring inbound SMTP handshaking
When debugging, it is often helpful to monitor the full SMTP handshaking process in real-time. The kcli client enables that for inbound connections with the