---
title: "Mail was held back from an agent"
method: POST
path: "message.held"
---

# Mail was held back from an agent

`POST message.held` (webhook)

Sent to your endpoint for `message.held`. Respond with a 2xx within 10 seconds; timeouts and non-2xx responses are retried on a backoff (7 attempts in total over about 21 hours). Redirects are not followed.

## Headers

- `X-SuperMail-Event` 'message.held', required
- `X-SuperMail-Delivery` string, required
- `X-SuperMail-Timestamp` string, required
- `X-SuperMail-Signature` string, required

## Payload

- object: Every webhook POST body. Verify `X-SuperMail-Signature: t=<unix>,v1=<hex>` where hex = HMAC-SHA256(secret, `<t>.<raw body>`), and reject timestamps more than 5 minutes old.
  - `id` string, required: Delivery id (also `X-SuperMail-Delivery`).
  - `event` 'message.held', required
  - `createdAt` string, date-time, required
  - `data` object, required: `message.held` — mail to an agent inbox was held back from the agent. Ids and the sender's address only: no subject, no snippet.
    - `holdId` string
    - `mailboxId` string
    - `mailbox` string, email
    - `threadId` string
    - `emailId` string, nullable
    - `from` string, email
    - `reason` 'auth_failed' | 'blocked_sender' | 'not_allowlisted' | 'unverified_sender'
    - `reasonText` string
    - `verdict` 'verified' | 'unverified' | 'failed'
    - `heldAt` string, date-time

## Acknowledgement `200`

Acknowledged.

---

[API](https://skmtc.dev/supermailos/apis/supermailos-api.md) · [All operations](https://skmtc.dev/supermailos/apis/supermailos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/supermailos/apis/supermailos-api/revisions/5bd0ce2ee269?raw)