---
tags:
  - bounce
---
# POST /api/admin/bounce/v1


!!! info
    This page was generated by extracting information from a JSON Schema
    data file for the API.  It may be missing some information, or otherwise
    suggest approximate or placeholder values based on information in the
    schema file; this is due to limitations on how that data is extracted
    from the underlying Rust code and into the JSON Schema, and then again
    from there and into these docs.

Allows the system operator to administratively bounce messages that match
certain criteria, or if no criteria are provided, ALL messages.

This API endpoint is used by the [kcli bounce](../../kcli/bounce.md) command.
!!! danger
    There is no way to undo the actions carried out by this request!

## Request Body

The request body is required.

The `Content-Type` header must be set to `application/json`.

Describes which messages should be bounced.
The criteria apply to the scheduled queue associated
with a given message.

!!! danger
    If you specify none of `domain`, `campaign`, `tenant`,
    `routing_domain` or `queue`, then **ALL** queues will
    be bounced.

    With great power comes great responsibility!


This is an object value, with the following properties:


  * `campaign` - optional nullable `string`. The campaign name to match. If omitted, any campaign will match.

  * `domain` - optional nullable `string`. The domain name to match. If omitted, any domain will match.

  * `duration` - optional nullable `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.

  * `expires` - optional nullable `string` (`date-time`). instead of specifying the duration, you can set an explicit
    expiration timestamp

  * `queue_names` - optional array of `string`. If present, queue_names takes precedence over `campaign`,
    `tenant`, and `domain` and specifies the exact set of
    scheduled queue names to which the bounce applies.

  * `reason` - required `string`. Reason to log in the delivery log. Each matching message will be bounced
    with an AdminBounce record unless you suppress logging.
    The reason will also be shown in the list of currently active admin
    bounces.

  * `routing_domain` - optional nullable `string`. The routing_domain name to match. If omitted, any routing_domain will match.
    {{since('2023.08.22-4d895015', inline=True)}}

  * `suppress_logging` - optional `boolean`. If true, do not generate AdminBounce delivery logs for matching
    messages.

  * `tenant` - optional nullable `string`. The tenant to match. If omitted, any tenant will match.

### Examples
```json
{
  "campaign": "campaign_name",
  "domain": "example.com",
  "duration": "20m",
  "expires": "1990-12-31T23:59:60Z",
  "queue_names": [
    "campaign_name:tenant_name@example.com"
  ],
  "reason": "Cleaning up a bad send",
  "routing_domain": "routing_domain.com",
  "suppress_logging": false,
  "tenant": "tenant_name"
}
```

## Responses
### Status 200
Bounce added successfully


`Content-Type: application/json`


This is an object value, with the following properties:


  * `bounced` - required `object`. Deprecated: this field is no longer populated, as bounces
    are now always asynchronous. In earlier versions the following
    applies:
    
    A map of queue name to number of bounced messages that
    were processed as part of the initial sweep.
    Additional bounces may be generated if/when other messages
    that match the rule are discovered, but those obviously
    cannot be reported in the context of the initial request.

  * `id` - required `string` (`uuid`). The id of the bounce rule that was registered.
    This can be used later to delete the rule if desired.

  * `total_bounced` - required `integer`. Deprecated: this field is no longer populated, as bounces are
    now always asynchronous. In earlier versions the following applies:
    
    The sum of the number of bounced messages reported by
    the `bounced` field.

### Examples
```json
{
  "bounced": {
    "gmail.com": 200,
    "yahoo.com": 100
  },
  "id": "552016f1-08e7-4e90-9da3-fd5c25acd069",
  "total_bounced": 300
}
```
