Skip to main content
OpenMail sends webhooks when inbound email is received. Emails that are blocked by sender rules or filtered out by allowlist mode do not trigger events.

​
Events

EventDescription
message.receivedA new inbound email was delivered to an inbox

​
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

FieldDescription
eventEvent type; currently always message.received
event_idUnique ID for this delivery. Use for deduplication - we may retry.
occurred_atWhen the event happened. Use to sort if events arrive out of order.
inbox_idThe inbox that received the message
thread_idConversation thread. Use with the API to fetch or send messages.
message.idUnique message ID
message.fromSender email address
message.subjectEmail subject line
message.body_textPlain-text body
message.attachmentsArray of attachments with url, parsedText (extracted content), and extractionMethod. See Attachments.

​
Headers

HeaderDescription
Content-Typeapplication/json
X-TimestampUnix timestamp (seconds) used in signature
X-SignatureHMAC-SHA256 signature
X-Event-IdUnique event ID for deduplication

Verification

HMAC signature verification.

Setup

Full implementation guide.