> ## Documentation Index > Fetch the complete documentation index at: https://openmail-docs-reputation-lifecycle-webhooks.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Events > OpenMail webhook event reference — event types, full payload structure, and field descriptions for inbound email and reputation lifecycle (inbox/pod suspension and reactivation) events. OpenMail sends webhooks when inbound email is received, and when the reputation engine suspends or reactivates one of your inboxes or pods. Emails that are blocked by [sender rules](/concepts/sender-rules) or filtered out by allowlist mode do not trigger events. ## Events | Event | Description | | ------------------- | ----------------------------------------------------------------------------- | | `message.received` | A new inbound email was delivered to an inbox | | `inbox.suspended` | An inbox was suspended (sending blocked) by the reputation engine or an admin | | `inbox.reactivated` | A previously suspended inbox was reactivated | | `pod.suspended` | A pod was suspended — every inbox in it is blocked from sending | | `pod.reactivated` | A previously suspended pod was reactivated | `inbox.*` and `pod.*` are **reputation lifecycle** events: they let you react when one of your end-users is cut off (for example, pause that agent) without your whole account being affected. We handle suspension automatically; these events tell you when it happens. They are delivered to your HTTP webhook only (not over [WebSockets](/concepts/websockets)). ## Use cases * **Agent routing** - Use `inbox_id` to route inbound email to the right user or container. * **Real-time replies** - Trigger your agent to process and reply within seconds of receipt. * **Multi-tenant** - Each inbox maps to an agent; `inbox_id` in the payload tells you which one. ## Payload structure ```json theme={"theme":{"light":"github-light","dark":"dark-plus"}} { "event": "message.received", "event_id": "evt_abc123", "occurred_at": "2024-03-21T10:05:00.000Z", "delivered_at": "2024-03-21T10:05:01.000Z", "attempt": 1, "inbox_id": "inb_92ma...", "thread_id": "thr_xyz...", "message": { "id": "msg_...", "rfc_message_id": "", "from": "sender@example.com", "to": "inbox@openmail.sh", "cc": [], "subject": "Email subject", "body_text": "Plain text body", "attachments": [ { "filename": "document.pdf", "contentType": "application/pdf", "sizeBytes": 12345, "url": "https://api.openmail.sh/v1/attachments/msg_.../document.pdf", "parsedText": "Invoice #2847\nDate: March 15, 2026\nAmount: $1,250.00", "extractionMethod": "pdf" } ], "received_at": "2024-03-21T10:05:00.000Z" } } ``` ## Field descriptions | Field | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `event` | Event type — e.g. `message.received` (see [Events](#events)) | | `event_id` | Unique ID for this delivery. Use for deduplication - we may retry. | | `occurred_at` | When the event happened. Use to sort if events arrive out of order. | | `inbox_id` | The inbox that received the message | | `thread_id` | Conversation thread. Use with the API to fetch or send messages. | | `message.id` | Unique message ID | | `message.from` | Sender email address | | `message.subject` | Email subject line | | `message.body_text` | Plain-text body | | `message.attachments` | Array of attachments with `url`, `parsedText` (extracted content), and `extractionMethod`. See [Attachments](/concepts/attachments). | ## Reputation lifecycle payload `inbox.suspended`, `inbox.reactivated`, `pod.suspended`, and `pod.reactivated` share the structure below. They carry a `reason` instead of a `message`. For `pod.*` events, `inbox_id` and `inbox_address` are `null`. ```json theme={"theme":{"light":"github-light","dark":"dark-plus"}} { "event": "inbox.suspended", "event_id": "evt_def456", "occurred_at": "2024-03-21T10:05:00.000Z", "inbox_id": "inb_92ma...", "inbox_address": "agent@yourdomain.com", "pod_id": "pod_abc...", "reason": "high_bounce_rate" } ``` | Field | Description | | --------------- | ------------------------------------------------------------------ | | `inbox_id` | The affected inbox, or `null` for `pod.*` events | | `inbox_address` | The affected inbox's email address, or `null` for `pod.*` events | | `pod_id` | The affected pod (or the suspended inbox's pod), if any | | `reason` | Why it was suspended (see below); `null` on `*.reactivated` events | ### Reason codes | Code | Meaning | | --------------------- | --------------------------------------------- | | `high_bounce_rate` | Too many of the inbox's recipients bounced | | `high_complaint_rate` | Too many recipients marked messages as spam | | `abuse` | Phishing or abusive sending was detected | | `pod_degraded` | The pod's overall sending health fell too far | | `manual_review` | Suspended by OpenMail staff pending review | | `other` | Suspended for another reason | A suspended inbox or pod is blocked from sending until reactivated. The reputation engine never auto-recovers a suspension — reactivation is an explicit action, which is when the `*.reactivated` event fires. ## Headers | Header | Description | | -------------- | ------------------------------------------ | | `Content-Type` | `application/json` | | `X-Timestamp` | Unix timestamp (seconds) used in signature | | `X-Signature` | HMAC-SHA256 signature | | `X-Event-Id` | Unique event ID for deduplication | HMAC signature verification. Full implementation guide.