Delivery Tracking

Track email delivery status via events and webhooks.

PlatformXe emits events for every stage of email delivery. Subscribe to these events to track delivery status, monitor bounce rates, and trigger follow-up actions.

Delivery events

Event	Description
`EMAIL_SENT`	Email accepted by the provider for delivery
`EMAIL_DELIVERED`	Email confirmed delivered to the recipient inbox
`EMAIL_BOUNCED`	Email bounced (hard or soft bounce)
`EMAIL_FAILED`	Email moved to dead-letter queue after exhausting all retries

Subscribing to events

Create an event subscription in the portal or via the API to receive delivery events as webhook payloads.

curl -X POST https://api.platformxe.com/api/v1/events/subscriptions \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "eventTypes": ["EMAIL_SENT", "EMAIL_DELIVERED", "EMAIL_BOUNCED", "EMAIL_FAILED"],
    "webhookUrl": "https://yourapp.com/webhooks/email-status",
    "secret": "your_webhook_signing_secret"
  }'

Webhook payload format

When a delivery event fires, PlatformXe sends a POST request to your webhook URL:

{
  "event": "EMAIL_DELIVERED",
  "timestamp": "2026-04-05T14:30:00.000Z",
  "data": {
    "messageId": "msg_abc123def456",
    "to": "jane@example.com",
    "subject": "Order #12345 Confirmed",
    "status": "delivered",
    "deliveredAt": "2026-04-05T14:30:00.000Z"
  }
}

For bounce events, additional fields are included:

{
  "event": "EMAIL_BOUNCED",
  "timestamp": "2026-04-05T14:31:00.000Z",
  "data": {
    "messageId": "msg_abc123def456",
    "to": "invalid@example.com",
    "subject": "Order #12345 Confirmed",
    "status": "bounced",
    "bounceType": "hard",
    "bounceReason": "Mailbox does not exist"
  }
}

Verifying webhook signatures

Each webhook request includes a x-platformxe-signature header. Verify it to ensure the request came from PlatformXe:

import { createHmac } from 'crypto';

function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret).update(payload).digest('hex');
  return expected === signature;
}

Always verify webhook signatures in production. Without verification, an attacker could send fake delivery events to your endpoint.

Delivery rate calculation

Use the event data to calculate your delivery rate:

delivery_rate = EMAIL_DELIVERED / (EMAIL_DELIVERED + EMAIL_BOUNCED + EMAIL_FAILED) * 100

A healthy delivery rate is above 95%. If your rate drops below this, review your recipient lists for invalid addresses and check for content that may trigger spam filters.