@bernierllc/email-webhook-events

Email event tracking, normalization, and analytics service for processing webhooks from all email providers (SendGrid, Mailgun, AWS SES, Postmark, SMTP2GO). Provides unified event format, real-time notifications, and comprehensive analytics aggregation.

Installation

npm install @bernierllc/email-webhook-events

Usage

Basic Setup

import { EmailWebhookEventsService, EmailProvider } from '@bernierllc/email-webhook-events';

const service = new EmailWebhookEventsService({
  providers: [
    {
      provider: EmailProvider.SENDGRID,
      enabled: true,
      webhookUrl: '/webhooks/sendgrid',
      secretKey: process.env.SENDGRID_WEBHOOK_SECRET!,
      signatureHeader: 'X-Twilio-Email-Event-Webhook-Signature',
      signatureAlgorithm: 'sha256'
    },
    {
      provider: EmailProvider.MAILGUN,
      enabled: true,
      webhookUrl: '/webhooks/mailgun',
      secretKey: process.env.MAILGUN_WEBHOOK_SECRET!,
      signatureHeader: 'X-Mailgun-Signature',
      signatureAlgorithm: 'sha256'
    }
  ],
  persistence: {
    enabled: true,
    adapter: 'memory' // or 'supabase', 'postgresql', 'mongodb'
  },
  analytics: {
    realTimeEnabled: true,
    aggregationInterval: 5000,
    retentionDays: 90
  },
  notifications: {
    enabled: true,
    criticalEvents: ['bounced', 'complained', 'failed'],
    channels: [
      { type: 'neverhub', config: {} }
    ]
  }
});

await service.initialize();

Processing Webhooks

// Express.js example
app.post('/webhooks/sendgrid', async (req, res) => {
  const webhook = {
    provider: EmailProvider.SENDGRID,
    signature: req.headers['x-twilio-email-event-webhook-signature'],
    payload: req.body,
    headers: req.headers
  };

  const result = await service.processWebhook(webhook);

  if (result.success) {
    res.status(200).json({ message: 'Event processed' });
  } else {
    res.status(400).json({ error: result.error });
  }
});

Querying Analytics

// Get analytics for the last 30 days
const startDate = new Date();
startDate.setDate(startDate.getDate() - 30);
const endDate = new Date();

const analytics = await service.getAnalytics(startDate, endDate);

console.log(`Delivery rate: ${(analytics.deliveryRate * 100).toFixed(2)}%`);
console.log(`Open rate: ${(analytics.openRate * 100).toFixed(2)}%`);
console.log(`Click rate: ${(analytics.clickRate * 100).toFixed(2)}%`);
console.log(`Bounce rate: ${(analytics.bounceRate * 100).toFixed(2)}%`);

// Filter by provider
const sendgridAnalytics = await service.getAnalytics(
  startDate,
  endDate,
  { provider: EmailProvider.SENDGRID }
);

// Filter by event type
const bounceAnalytics = await service.getAnalytics(
  startDate,
  endDate,
  { eventTypes: ['bounced'] }
);

Querying Events

// Get all events for a specific email
const emailEvents = await service.getEventsForEmail('email-123');

// Query events with filters
const events = await service.queryEvents({
  recipient: '[email protected]',
  eventTypes: ['opened', 'clicked'],
  startDate: new Date('2025-01-01'),
  endDate: new Date('2025-12-31'),
  limit: 100
});

API Reference

EmailWebhookEventsService

constructor(config: EmailWebhookEventsConfig)

Creates a new EmailWebhookEventsService instance.

Parameters:

• config.providers - Array of provider configurations
• config.persistence - Persistence settings (optional)
• config.analytics - Analytics settings (optional)
• config.notifications - Notification settings (optional)
• config.rateLimiting - Rate limiting settings (optional)

async initialize(): Promise<void>

Initializes the service. Must be called before processing webhooks.

async processWebhook(webhook: WebhookPayload): Promise<EmailWebhookResult>

Processes an incoming webhook from an email provider.

Parameters:

• webhook.provider - Email provider (sendgrid, mailgun, aws_ses, etc.)
• webhook.signature - Webhook signature for validation
• webhook.payload - Raw webhook payload
• webhook.headers - Request headers

Returns: EmailWebhookResult with success status and normalized event

async getAnalytics(startDate: Date, endDate: Date, filters?: AnalyticsFilters): Promise<EmailAnalytics>

Retrieves analytics for the specified date range.

Parameters:

• startDate - Start of date range
• endDate - End of date range
• filters - Optional filters (provider, emailId, recipient, eventTypes)

Returns: EmailAnalytics with counts, rates, and breakdowns

async queryEvents(query: EventQuery): Promise<EmailEvent[]>

Queries events with various filters.

Parameters:

• query.emailId - Filter by email ID
• query.recipient - Filter by recipient
• query.eventTypes - Filter by event types
• query.startDate - Filter by start date
• query.endDate - Filter by end date
• query.limit - Maximum number of results
• query.offset - Offset for pagination

Returns: Array of EmailEvent

async getEventsForEmail(emailId: string): Promise<EmailEvent[]>

Gets all events for a specific email.

Parameters:

• emailId - Email identifier

Returns: Array of EmailEvent

Supported Providers

SendGrid

{
  provider: EmailProvider.SENDGRID,
  signatureHeader: 'X-Twilio-Email-Event-Webhook-Signature',
  signatureAlgorithm: 'sha256'
}

Supported Events: delivered, open, click, bounce, spamreport, unsubscribe, deferred, dropped

Mailgun

{
  provider: EmailProvider.MAILGUN,
  signatureHeader: 'X-Mailgun-Signature',
  signatureAlgorithm: 'sha256'
}

Supported Events: delivered, opened, clicked, bounced, complained, unsubscribed, failed

AWS SES

{
  provider: EmailProvider.AWS_SES,
  signatureHeader: 'X-Amz-Sns-Message-Type',
  signatureAlgorithm: 'sha256'
}

Supported Events: Delivery, Open, Click, Bounce, Complaint, Reject

Postmark

{
  provider: EmailProvider.POSTMARK,
  signatureHeader: 'X-Postmark-Signature',
  signatureAlgorithm: 'sha256'
}

Supported Events: Delivery, Open, Click, Bounce, SpamComplaint, SubscriptionChange

SMTP2GO

{
  provider: EmailProvider.SMTP2GO,
  signatureHeader: 'X-Smtp2go-Signature',
  signatureAlgorithm: 'sha256'
}

Supported Events: delivered, open, click, bounce, failed

Event Types

All provider events are normalized to these unified types:

• DELIVERED - Email successfully delivered
• OPENED - Email opened by recipient
• CLICKED - Link clicked in email
• BOUNCED - Email bounced (hard or soft)
• COMPLAINED - Spam complaint received
• UNSUBSCRIBED - Recipient unsubscribed
• FAILED - Email delivery failed
• DEFERRED - Email delivery deferred
• DROPPED - Email dropped by provider

Analytics Metrics

Counts

• totalSent - Total emails sent
• totalDelivered - Total emails delivered
• totalOpened - Total emails opened
• totalClicked - Total links clicked
• totalBounced - Total emails bounced
• totalComplained - Total spam complaints
• totalUnsubscribed - Total unsubscribes
• totalFailed - Total delivery failures

Rates

• deliveryRate - delivered / sent
• openRate - opened / delivered
• clickRate - clicked / delivered
• clickToOpenRate - clicked / opened
• bounceRate - bounced / sent
• complaintRate - complained / sent
• unsubscribeRate - unsubscribed / delivered

Breakdowns

• byProvider - Analytics per provider
• byEventType - Counts per event type
• byBounceType - Hard vs soft bounces
• topLinks - Most clicked links
• byDevice - Desktop, mobile, tablet breakdown

Configuration

Environment Variables

# Provider webhook secrets
EMAIL_WEBHOOK_SENDGRID_SECRET=your-sendgrid-webhook-secret
EMAIL_WEBHOOK_MAILGUN_SECRET=your-mailgun-webhook-secret
EMAIL_WEBHOOK_SES_SECRET=your-ses-sns-topic-subscription-secret
EMAIL_WEBHOOK_POSTMARK_SECRET=your-postmark-webhook-secret

# Persistence
EMAIL_WEBHOOK_PERSISTENCE_ENABLED=true
EMAIL_WEBHOOK_PERSISTENCE_ADAPTER=memory
EMAIL_WEBHOOK_PERSISTENCE_RETENTION_DAYS=90

# Analytics
EMAIL_WEBHOOK_ANALYTICS_REALTIME=true
EMAIL_WEBHOOK_ANALYTICS_INTERVAL=5000

# Notifications
EMAIL_WEBHOOK_NOTIFICATIONS_ENABLED=true

# Rate limiting
EMAIL_WEBHOOK_RATE_LIMIT_ENABLED=false
EMAIL_WEBHOOK_RATE_LIMIT_MAX_PER_SECOND=100

Integration Testing

This package includes integration tests that use real SendGrid webhooks.

Prerequisites

1. SendGrid account with API key
2. Paid ngrok account with auth token
3. Test email address
4. .env.test file configured with:
   • SENDGRID_API_KEY
   • SENDGRID_WEBHOOK_SECRET (optional)
   • TEST_EMAIL
   • NGROK_AUTH_TOKEN
   • NGROK_RESERVED_DOMAIN (optional, for consistent URLs)
   • WEBHOOK_SERVER_PORT (optional, defaults to 3000)

Running Integration Tests

1. Ensure .env.test file is configured with all required variables
2. Set RUN_INTEGRATION_TESTS=true environment variable
3. Configure SendGrid webhook URL (first time only, or use reserved domain):
   • Run test once to get webhook URL from output, or
   • Use reserved domain: https://your-reserved-domain.ngrok.io/webhooks/sendgrid
   • Go to SendGrid dashboard → Settings → Mail Settings → Event Webhook
   • Set webhook URL and enable all event types
4. Run tests: npm test -- sendgrid-webhook-integration

Tests automatically:

• Start webhook server
• Create ngrok tunnel (programmatically)
• Send test emails via @bernierllc/email-manager
• Capture and process webhooks
• Save payloads to __tests__/fixtures/sendgrid-webhooks/

Captured Payloads

Real webhook payloads are captured in __tests__/fixtures/sendgrid-webhooks/ and used to generate accurate mocks for unit tests.

See __tests__/fixtures/sendgrid-webhooks/README.md for more details.

Integration Status

• Logger: integrated - Uses MockLogger (pending @bernierllc/logger publication)
• Docs-Suite: ready - TypeScript interfaces with JSDoc comments
• NeverHub: required - Event publishing and service discovery (pending implementation)

Examples

See the examples/ directory for complete usage examples:

• setup-sendgrid.ts - SendGrid webhook setup
• setup-mailgun.ts - Mailgun webhook setup
• query-analytics.ts - Analytics query examples
• critical-events.ts - Critical event handling

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

This package is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.

See Also

• @bernierllc/webhook-processor - Generic webhook processing (pending)
• @bernierllc/email-sender - Email sending service
• @bernierllc/email-campaign-management - Campaign management (pending)