Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openmail.sh/llms.txt

Use this file to discover all available pages before exploring further.

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.