Receive inbound email as JSON with a webhook

Every inbound email reaches your webhook as JSON.

POST/v1/webhook-endpointswebhooks:manage

Add a webhook endpoint

Request

curl -X POST "https://api.iotabot.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $IOTABOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://crm.acme.com/iotabot",
  "channels": [
    "email"
  ],
  "events": [
    "message.received"
  ]
}'

Response · 201

{
  "data": {
    "id": "6a4bb0…",
    "object": "webhook_endpoint",
    "url": "https://crm.acme.com/iotabot",
    "status": "active",
    "secret": "whsec_…",
    "verification": {
      "verified": true,
      "reason": null
    }
  }
}

WEBHOOKmessage.received

html is safe to render; html_raw is exactly as received. email carries from, to, cc, in_reply_to and references.

{
  "id": "evt_6a4ba40bc3f1a2b3c4d5e750",
  "object": "event",
  "type": "message.received",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T09:15:02.881Z",
  "livemode": true,
  "channel": "email",
  "website_id": "6a4b3fbbe291bce5bf701c5c",
  "data": {
    "message": {
      "id": "6a4b9e5dc3f1a2b3c4d5e701",
      "object": "message",
      "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
      "channel": "email",
      "direction": "inbound",
      "sender": {
        "type": "visitor",
        "name": null
      },
      "type": "email",
      "text": "Hi, where is my order #1042?",
      "html": "<p>Hi, where is my order #1042?</p>",
      "html_raw": "<div dir=\"ltr\"><p>Hi, where is my order #1042?</p></div>",
      "attachments": [],
      "status": "received",
      "delivery": null,
      "created_at": "2026-10-01T09:15:02.881Z",
      "email": {
        "subject": "Order #1042",
        "mailbox": "support@acme.com",
        "customer": "priya@example.com",
        "message_id": "<CAF3kq1x@mail.gmail.com>",
        "thread_id": "<CAF3kq1x@mail.gmail.com>",
        "from": "priya@example.com",
        "to": [
          "support@acme.com"
        ],
        "cc": [],
        "in_reply_to": null,
        "references": null
      }
    },
    "conversation": {
      "id": "6a4b9e21c3f1a2b3c4d5e6f7",
      "object": "conversation",
      "channel": "email",
      "website_id": "6a4b3fbbe291bce5bf701c5c",
      "status": "open",
      "mode": "ai",
      "subject": "Order #1042",
      "contact": {
        "name": "Priya Sharma",
        "email": "priya@example.com",
        "phone": null,
        "external_id": null
      },
      "assigned_agent_id": null,
      "tags": [],
      "integration_replies": true,
      "message_count": 3,
      "created_at": "2026-10-01T09:12:44.120Z",
      "last_message_at": "2026-10-01T09:15:02.881Z"
    }
  }
}