Webhook Event Types

Gork emits five events. Subscribe per endpoint with subscribedEvents (or "*" for all). Every delivery also carries X-Gork-Event with the event name, so one endpoint can route on the header.

email.received

A new inbound email arrived, was parsed, sanitized, and stored. This is the event that wakes your agent.

{
  "event": "email.received",
  "message": {
    "id": "msg_908123acdf00000000000001",
    "inboxId": "inb_728af980b4e0000000000001",
    "threadId": "thd_128bca90f400000000000001",
    "agent": { "id": "agt_128bca90f400000000000001", "name": "Alex (SDR)" },
    "from": { "address": "prospect@acmecorp.com", "name": "Marcus Reid" },
    "to": ["alex@outbound.yourdomain.com"],
    "subject": "Re: Partnership proposal",
    "text": "Hi Alex,\n\nWe would love to connect this week.",
    "html": "<p>Hi Alex,<br/><br/>We would love to connect this week.</p>",
    "attachmentsCount": 0,
    "receivedAt": "2026-09-22T12:34:56.789Z"
  },
  "sender": {
    "kind": "human",
    "confidence": "low",
    "evidence": []
  }
}

agent is null when the inbox has no agent attached. sender.kind is human, agent, or automated — classified from automation headers (Auto-Submitted, X-Autoreply, Precedence) and out-of-office subject patterns, with the supporting evidence included. Branch on it: an automated sender is usually an out-of-office reply, not a human waiting for an answer.

email.sent

An outbound send through POST /v1/messages/send was accepted by the provider.

{
  "event": "email.sent",
  "message": {
    "id": "msg_908123acdf00000000000002",
    "inboxId": "inb_728af980b4e0000000000001",
    "threadId": "thd_128bca90f400000000000001",
    "to": ["prospect@acmecorp.com"],
    "subject": "Re: Partnership proposal",
    "status": "delivered",
    "providerMessageId": "01000123456789ab-abcdef01-2345-6789-abcd-ef0123456789-000000",
    "sentAt": "2026-09-22T12:35:10.000Z"
  }
}

email.bounced

The recipient mail server rejected the message. reason is hard_bounce (permanent — the address is automatically suppressed) or soft_bounce (transient — the message status is updated but the address is not suppressed). messageId is the Gork message id when the bounce could be matched to a sent message, otherwise null.

{
  "event": "email.bounced",
  "email": "gone@example.com",
  "reason": "hard_bounce",
  "diagnostic": "smtp; 550 5.1.1 user unknown",
  "messageId": "msg_908123acdf00000000000002",
  "timestamp": "2026-09-22T12:36:00.000Z"
}

email.complained

A recipient flagged the message as spam via a feedback loop. The address is automatically suppressed — stop mailing it.

{
  "event": "email.complained",
  "email": "annoyed@example.com",
  "reason": "complaint",
  "diagnostic": null,
  "messageId": "msg_908123acdf00000000000002",
  "timestamp": "2026-09-22T12:37:00.000Z"
}

email.unsubscribed

A recipient completed one-click unsubscribe. The address is suppressed with reason unsubscribed — remove it from future campaigns.

{
  "event": "email.unsubscribed",
  "email": "tired@example.com",
  "organizationId": "org_9f2c41ab77d04e1c90ab33de",
  "unsubscribedAt": "2026-09-22T12:38:00.000Z"
}

Deliveries are at-least-once: a crash between the customer POST and bookkeeping can redeliver the same attempt. Dedupe on X-Gork-Delivery, which is stable per delivery attempt.

Getting Started

AI & Agents

SDKs & Tools

Guides

Webhooks

Security

Account

Solutions

Resources

Webhook Event Types

email.received

email.sent

email.bounced

email.complained

email.unsubscribed

​email.received

​email.sent

​email.bounced

​email.complained

​email.unsubscribed

email.received

email.sent

email.bounced

email.complained

email.unsubscribed