MailingCore
DocumentationWebhook event catalog

Webhook event catalog

Payload reference for email.* and contact.unsubscribed events.

Reference for outbound webhook event types. Register endpoints in Webhooks overview.

Event types

EventWhen it fires
email.sentMessage accepted and handed to the transport queue
email.deliveredProvider confirms delivery to recipient MX
email.openedTracking pixel loaded (if enabled)
email.clickedTracked link clicked
email.bouncedHard or soft bounce from provider
email.complainedSpam complaint (FBL)
email.failedSend failed before or during delivery
contact.unsubscribedRecipient used hosted unsubscribe or API unsubscribe

Envelope shape

Each delivery is a signed POST to your URL:

X-MailingCore-Signature: t=1719763200,v1=abc123...
Content-Type: application/json

{
  "id": "evt_...",
  "type": "email.delivered",
  "createdAt": "2026-06-30T12:00:00.000Z",
  "tenantId": "clxtenant...",
  "data": { }
}

Verify with HMAC signature before trusting data.

email.* data (common fields)

{
  "emailLogId": "clxlog...",
  "to": "[email protected]",
  "subject": "Welcome",
  "status": "DELIVERED",
  "tags": ["welcome"],
  "metadata": { "userId": "123" },
  "templateVersionId": "clxversion...",
  "occurredAt": "2026-06-30T12:00:01.000Z"
}

Event-specific additions:

EventExtra fields
email.bouncedbounceType (hard / soft), diagnostic
email.complainedcomplaintFeedbackType
email.openeduserAgent, ip (if collected)
email.clickedlinkUrl, linkId

contact.unsubscribed data

{
  "contactId": "clxcontact...",
  "externalId": "user-12345",
  "email": "[email protected]",
  "unsubscribedAt": "2026-06-30T12:00:00.000Z",
  "source": "hosted_page"
}

Use this to sync unsubscribes back to your CRM and stop future campaigns.

Processing tips

  1. Respond 200 within a few seconds; process asynchronously.
  2. Use id (or emailLogId) for deduplication — retries are expected.
  3. On email.bounced (hard) or contact.unsubscribed, add the address to your local suppression logic.

Related