Skip to content

POST /api/admin/bounce/v1

Making a POST request to this endpoint allows the system operator to administratively bounce messages that match certain criteria, or if no criteria are provided, ALL messages.

Danger

There is no way to undo the actions carried out by this request!

The body of the post request must be a JSON object; here's an example:

{
    "domain": "gmail.com",
    "reason": "no time to explain!11!"
}

and the response will look something like this, with an entry for each matching queue name and the count of matching messages that were bounced so far:

{"bounced":{"gmail.com":42}, "total_bounced":42}

Note

More recent builds of KumoMTA perform most of the bouncing asynchronously with respect to this bounce request being made, in order to make the overall system more responsive and performant. As a result, the numbers reported in the response to this command will often show as either zero or some smaller number than the total that will be affected. Use the GET /api/admin/bounce/v1 API or the kcli bounce-list command to review the current totals.

The following fields are possible in the request:

domain

Optional string. The domain name to match. If omitted, any domain will match.

routing_domain

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.

Optional string. The routing_domain name to match. If omitted, any routing_domain will match.

campaign

Optional string. The campaign name to match. If omitted, any campaign will match.

tenant

Optional string. The tenant to match. If omitted, any tenant will match.

Danger

If you specify none of domain, campaign or tenant, then ALL queues will be bounced.

With great power, comes great responsibility!

reason

Required. Reason to log in the delivery log.

duration

Optional duration string. Defaults to "5m". Specifies how long this bounce directive remains active.

While active, newly injected messages that match the bounce criteria will also be bounced.

Kumo CLI

In addition to making raw API requests, you may use the kumo CLI:

$ kcli --endpoint http://127.0.0.1:8000 bounce --everything --reason purge
{
  "id": "0234c7c9-afd3-49f9-9a4c-a1cc37fcc53b",
  "bounced": {},
  "total_bounced": 0
}

Run kcli bounce --help for more informtion.