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 or filtered out by allowlist mode do not trigger 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).

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

{
  "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": "<original@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)
`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.

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.

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

Verification

HMAC signature verification.

Setup

Full implementation guide.

Get started

Core concepts

WebSockets

Webhooks

Guides

Integrations

Best practices

Resources

Security & privacy

Events

Events

Use cases

Payload structure

Field descriptions

Reputation lifecycle payload

Reason codes

Headers

Verification

Setup

​Events

​Use cases

​Payload structure

​Field descriptions

​Reputation lifecycle payload

​Reason codes

​Headers

Verification

Setup

Events

Use cases

Payload structure

Field descriptions

Reputation lifecycle payload

Reason codes

Headers