Skip to content

POST /api/admin/bounce/v1

Note

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.

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.

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.

  • 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

{
  "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

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