Webhook Events Reference

Complete reference for all webhook event types and their payload schemas.

---

Common fields

Every webhook payload includes these top-level fields:

Field	Type	Description
event_type	string	The event type (see below)
timestamp	string	ISO 8601 UTC timestamp when the event occurred
data	object	Event-specific data (see per-event schemas below)

---

delivered

Email was successfully delivered to the recipient’s mail server.

{
  "event_type": "delivered",
  "timestamp": "2026-04-20T14:30:05Z",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_email": "user@example.com",
    "subject": "Your order is confirmed",
    "tls": true
  }
}

Field	Description
message_id	UUID of the message
to_email	Recipient address
subject	Email subject
tls	Whether the connection used TLS encryption

---

soft_bounced

Temporary delivery failure. Emitlo will retry automatically.

{
  "event_type": "soft_bounced",
  "timestamp": "2026-04-20T14:30:10Z",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_email": "user@example.com",
    "subject": "Your order is confirmed",
    "dsn_status": "4.2.2",
    "dsn_message": "Mailbox full"
  }
}

---

hard_bounced

Permanent delivery failure. The address is automatically added to your suppression list.

{
  "event_type": "hard_bounced",
  "timestamp": "2026-04-20T14:30:10Z",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_email": "invalid@example.com",
    "subject": "Your order is confirmed",
    "dsn_status": "5.1.1",
    "dsn_action": "failed",
    "dsn_message": "User unknown"
  }
}

Field	Description
dsn_status	DSN status code (e.g. 5.1.1)
dsn_action	DSN action (e.g. failed)
dsn_message	Human-readable diagnostic message from the remote server

---

complained

Recipient marked the email as spam. The address is automatically added to your suppression list.

{
  "event_type": "complained",
  "timestamp": "2026-04-20T15:00:00Z",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_email": "user@example.com",
    "subject": "Your order is confirmed",
    "feedback_type": "abuse"
  }
}

---

opened

Recipient opened the email.

{
  "event_type": "opened",
  "timestamp": "2026-04-20T16:00:00Z",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_email": "user@example.com",
    "subject": "Your order is confirmed"
  }
}

---

clicked

Recipient clicked a tracked link.

{
  "event_type": "clicked",
  "timestamp": "2026-04-20T16:05:00Z",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_email": "user@example.com",
    "subject": "Your order is confirmed",
    "url": "https://yourapp.com/dashboard"
  }
}

---

unsubscribed

Recipient clicked the unsubscribe link. The address is automatically added to your suppression list.

{
  "event_type": "unsubscribed",
  "timestamp": "2026-04-20T17:00:00Z",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_email": "user@example.com"
  }
}

---

deferred

Delivery was delayed. Emitlo will retry automatically.

{
  "event_type": "deferred",
  "timestamp": "2026-04-20T14:30:10Z",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_email": "user@example.com",
    "deferred_count": 2,
    "reason": "Connection timeout"
  }
}

---

Webhook headers

Every webhook request includes these HTTP headers:

Header	Description
X-Emitlo-Signature	sha256=<hmac> — HMAC-SHA256 of the raw body using your webhook secret
X-Emitlo-Event	The event type (e.g. delivered)
X-Emitlo-Delivery-Id	Unique UUID for this delivery attempt — use for deduplication
Content-Type	application/json

See Webhooks Guide for signature verification examples.