---
title: "Send a notification-style bounce to the original sender"
method: POST
path: "/v1/mailboxes/{mailbox_id}/messages/{email_id}/bounce"
tags: ["threads"]
---

# Send a notification-style bounce to the original sender

`POST /v1/mailboxes/{mailbox_id}/messages/{email_id}/bounce`

## Request

- Base URL: `https://mbag.ai/api`
- URL: `https://mbag.ai/api/v1/mailboxes/{mailbox_id}/messages/{email_id}/bounce`
- Auth: HTTP bearer

`reason` is used verbatim as the bounce's explanation paragraph. A
human-triggered action (API-key auth), so Supervised mode does not
hold it — only Shadow mode (nothing ever leaves) refuses it.

## Path parameters

- `mailbox_id` integer, required
- `email_id` string, required

## Request body

- BounceRequest
  - `reason` string, required: Used verbatim as the bounce explanation paragraph.

## Response `200`

Bounce sent.

- BounceResponse
  - `success` boolean, required

## Other responses

- `401`: Missing or invalid credential, raised by the `ApiKeyAuth` extractor (`backend/src/api_keys.rs`) before the handler runs: no `Authorization` header, a non-`Bearer` scheme, a key that doesn't hash-match any row, or a key whose status isn't `active`. A header that isn't valid UTF-8, has no scheme token, or has `Bearer` with no key value returns 400 with this same JSON shape instead of 401.
- `404`: Mailbox not found (or not owned by the caller). Note: any database error on this lookup ALSO surfaces as this same 404 (same `fetch_one().map_err(|_| ...)` pattern as the reply endpoint).
- `409`: Bounces are suppressed while this mailbox is in shadow assessment mode.
- `422`: The original message has no sender to bounce to.
- `429`: Bounce rate limit exceeded (fixed at 60/hour per mailbox — not tier-dependent). Body is `{"error": "Bounce rate limit exceeded (60/hour)"}`, with no separate machine-readable rule field.
- `502`: Failed to read the mailbox's operating mode, failed to fetch the original message via JMAP, or failed to send the bounce. Message text is a wrapped upstream error string.

---

[API](https://skmtc.dev/mailbuttons/apis/mailbuttons-agent-mail-api.md) · [All operations](https://skmtc.dev/mailbuttons/apis/mailbuttons-agent-mail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailbuttons/apis/mailbuttons-agent-mail-api/revisions/fe2761823978?raw)