Email Tracking & Analytics

Monitor your email performance with comprehensive tracking capabilities. Track deliverability, opens, clicks, conversions, and user engagement with real-time analytics and detailed reporting.

Email Delivery Tracking

Monitor email delivery status and identify delivery issues:

import &#123; OMXClient &#125; from '@omx-sdk/email';

const omx = new OMXClient(&#123;
  clientId: 'your_client_id',
  secretKey: 'your_secret_key'
&#125;);

// Send email with tracking enabled
const result = await omx.email.send(&#123;
  to: 'user@example.com',
  subject: 'Welcome to our platform',
  template: 'welcome_email',
  
  // Enable delivery tracking
  tracking: &#123;
    delivery: true,
    opens: true,
    clicks: true,
    unsubscribes: true
  &#125;,
  
  // Custom tracking parameters
  metadata: &#123;
    campaignId: 'welcome_campaign_2024',
    userSegment: 'new_users',
    source: 'signup_flow'
  &#125;
&#125;);

// Get delivery status
const deliveryStatus = await omx.email.getDeliveryStatus(result.messageId);
console.log(deliveryStatus);
// &#123;
//   messageId: 'msg_123456',
//   status: 'delivered',
//   timestamp: '2024-01-15T10:30:00Z',
//   recipient: 'user@example.com',
//   deliveryAttempts: 1,
//   latency: 2.3, // seconds
//   provider: 'gmail',
//   bounceReason: null
// &#125;

// Track delivery events in real-time
const deliveryStream = omx.email.streamDeliveryEvents();

deliveryStream.on('delivered', (event) =&gt; &#123;
  console.log(`Email $&#123;event.messageId&#125; delivered to $&#123;event.recipient&#125;`);
  updateDeliveryMetrics(event);
&#125;);

deliveryStream.on('bounced', (event) =&gt; &#123;
  console.log(`Email bounced: $&#123;event.bounceReason&#125;`);
  handleBounce(event);
&#125;);

deliveryStream.on('complaint', (event) =&gt; &#123;
  console.log(`Spam complaint from $&#123;event.recipient&#125;`);
  handleComplaint(event);
&#125;);

Open and Click Tracking

Track when recipients open emails and click on links:

// Email with advanced tracking
const trackedEmail = await omx.email.send(&#123;
  to: 'user@example.com',
  template: 'newsletter',
  
  tracking: &#123;
    // Open tracking with detailed analytics
    opens: &#123;
      enabled: true,
      trackLocation: true,
      trackDevice: true,
      trackReads: true, // Track read time
      pixelless: false // Use 1x1 pixel tracking
    &#125;,
    
    // Click tracking with link analytics
    clicks: &#123;
      enabled: true,
      trackAllLinks: true,
      customDomains: ['track.yourapp.com'],
      
      // Custom tracking for specific links
      customLinks: &#123;
        'cta_button': &#123; goal: 'conversion', value: 50 &#125;,
        'product_link': &#123; goal: 'product_view', category: 'electronics' &#125;
      &#125;
    &#125;,
    
    // UTM parameters for analytics integration
    utm: &#123;
      source: 'email',
      medium: 'newsletter',
      campaign: 'january_2024',
      content: 'main_cta'
    &#125;
  &#125;
&#125;);

// Get open tracking data
const openData = await omx.email.getOpenTracking(result.messageId);
console.log(openData);
// &#123;
//   messageId: 'msg_123456',
//   opens: [
//     &#123;
//       timestamp: '2024-01-15T11:00:00Z',
//       userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)...',
//       device: &#123; type: 'mobile', os: 'iOS', browser: 'Mobile Safari' &#125;,
//       location: &#123; country: 'US', city: 'New York', region: 'NY' &#125;,
//       readTime: 45, // seconds
//       isUnique: true
//     &#125;
//   ],
//   uniqueOpens: 1,
//   totalOpens: 3,
//   openRate: 0.75,
//   avgReadTime: 32
// &#125;

// Get click tracking data
const clickData = await omx.email.getClickTracking(result.messageId);
console.log(clickData);
// &#123;
//   messageId: 'msg_123456',
//   clicks: [
//     &#123;
//       timestamp: '2024-01-15T11:05:00Z',
//       url: 'https://yourapp.com/products/123',
//       linkId: 'product_link',
//       userAgent: 'Mozilla/5.0...',
//       device: &#123; type: 'mobile', os: 'iOS' &#125;,
//       location: &#123; country: 'US', city: 'New York' &#125;,
//       isUnique: true
//     &#125;
//   ],
//   uniqueClicks: 1,
//   totalClicks: 2,
//   clickRate: 0.15,
//   clickToOpenRate: 0.20
// &#125;

Campaign Analytics

Analyze performance across email campaigns and segments:

// Get campaign analytics
const campaignAnalytics = await omx.email.getCampaignAnalytics('welcome_campaign_2024', &#123;
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  granularity: 'daily',
  
  // Metrics to include
  metrics: [
    'sent',
    'delivered',
    'bounced',
    'opened',
    'clicked',
    'unsubscribed',
    'complained',
    'conversions'
  ],
  
  // Breakdown by segments
  segmentBy: ['userSegment', 'device', 'location']
&#125;);

console.log(campaignAnalytics);
// &#123;
//   campaign: 'welcome_campaign_2024',
//   period: &#123; start: '2024-01-01', end: '2024-01-31' &#125;,
//   
//   summary: &#123;
//     sent: 12500,
//     delivered: 12180,
//     deliveryRate: 0.974,
//     bounced: 320,
//     bounceRate: 0.026,
//     opened: 4876,
//     openRate: 0.40,
//     uniqueOpens: 4123,
//     uniqueOpenRate: 0.34,
//     clicked: 732,
//     clickRate: 0.06,
//     uniqueClicks: 651,
//     uniqueClickRate: 0.053,
//     clickToOpenRate: 0.15,
//     unsubscribed: 45,
//     unsubscribeRate: 0.004,
//     complained: 8,
//     complaintRate: 0.0007,
//     conversions: 89,
//     conversionRate: 0.007
//   &#125;,
//   
//   timeline: [
//     &#123; date: '2024-01-01', sent: 450, opened: 180, clicked: 27 &#125;,
//     &#123; date: '2024-01-02', sent: 520, opened: 208, clicked: 31 &#125;
//   ],
//   
//   segments: &#123;
//     userSegment: &#123;
//       'new_users': &#123; sent: 8000, openRate: 0.45, clickRate: 0.08 &#125;,
//       'existing_users': &#123; sent: 4500, openRate: 0.32, clickRate: 0.04 &#125;
//     &#125;,
//     device: &#123;
//       'mobile': &#123; opens: 2800, openRate: 0.42, avgReadTime: 28 &#125;,
//       'desktop': &#123; opens: 1900, openRate: 0.38, avgReadTime: 45 &#125;
//     &#125;
//   &#125;
// &#125;

// Compare campaign performance
const comparison = await omx.email.compareCampaigns([
  'welcome_campaign_2024',
  'promotional_campaign_2024',
  'newsletter_campaign_2024'
], &#123;
  metrics: ['openRate', 'clickRate', 'conversionRate'],
  timeRange: '30d'
&#125;);

// Get industry benchmarks
const benchmarks = await omx.email.getBenchmarks(&#123;
  industry: 'e-commerce',
  emailType: 'promotional',
  region: 'US'
&#125;);

console.log('Your performance vs benchmarks:', &#123;
  yourOpenRate: campaignAnalytics.summary.openRate,
  benchmarkOpenRate: benchmarks.openRate,
  performance: campaignAnalytics.summary.openRate &gt; benchmarks.openRate ? 'above' : 'below'
&#125;);

User Engagement Tracking

Track individual user engagement patterns and behavior:

// Get user engagement profile
const userEngagement = await omx.email.getUserEngagement('user@example.com', &#123;
  timeRange: '90d',
  includeDetails: true
&#125;);

console.log(userEngagement);
// &#123;
//   email: 'user@example.com',
//   engagementScore: 75, // 0-100 scale
//   
//   summary: &#123;
//     emailsReceived: 45,
//     emailsOpened: 32,
//     emailsClicked: 12,
//     avgOpenTime: 18, // hours after send
//     avgReadTime: 34, // seconds
//     mostActiveDay: 'tuesday',
//     mostActiveTime: '10:00-11:00',
//     preferredDevice: 'mobile'
//   &#125;,
//   
//   preferences: &#123;
//     frequency: 'weekly',
//     categories: ['product_updates', 'promotions'],
//     unsubscribedCategories: ['newsletters'],
//     timezone: 'America/New_York'
//   &#125;,
//   
//   recentActivity: [
//     &#123;
//       messageId: 'msg_789',
//       campaign: 'welcome_series',
//       action: 'clicked',
//       timestamp: '2024-01-14T10:30:00Z',
//       link: 'product_page'
//     &#125;
//   ]
// &#125;

// Track engagement over time
const engagementTrend = await omx.email.getEngagementTrend('user@example.com', &#123;
  timeRange: '6m',
  granularity: 'weekly'
&#125;);

// Segment users by engagement level
const engagementSegments = await omx.email.segmentByEngagement(&#123;
  criteria: &#123;
    highly_engaged: &#123; openRate: '&gt; 0.6', clickRate: '&gt; 0.1' &#125;,
    moderately_engaged: &#123; openRate: '0.2-0.6', clickRate: '0.02-0.1' &#125;,
    low_engaged: &#123; openRate: '&lt; 0.2', clickRate: '&lt; 0.02' &#125;,
    inactive: &#123; lastOpen: '&gt; 30d' &#125;
  &#125;,
  timeRange: '90d'
&#125;);

console.log('Engagement segments:', engagementSegments);
// &#123;
//   highly_engaged: &#123; count: 1250, percentage: 25 &#125;,
//   moderately_engaged: &#123; count: 2750, percentage: 55 &#125;,
//   low_engaged: &#123; count: 800, percentage: 16 &#125;,
//   inactive: &#123; count: 200, percentage: 4 &#125;
// &#125;

Conversion Tracking

Track email-driven conversions and revenue attribution:

// Set up conversion tracking
const conversionTracking = await omx.email.setupConversions(&#123;
  events: [
    &#123;
      name: 'purchase',
      value: 'revenue',
      attributionWindow: '7d',
      trackingMethod: 'utm'
    &#125;,
    &#123;
      name: 'signup',
      value: 50, // fixed value
      attributionWindow: '3d',
      trackingMethod: 'pixel'
    &#125;,
    &#123;
      name: 'trial_start',
      value: 25,
      attributionWindow: '24h',
      trackingMethod: 'api'
    &#125;
  ],
  
  // Conversion pixel
  pixel: &#123;
    enabled: true,
    domains: ['yourapp.com', 'checkout.yourapp.com']
  &#125;
&#125;);

// Track conversions via API
await omx.email.trackConversion(&#123;
  messageId: 'msg_123456',
  userId: 'user_789',
  event: 'purchase',
  value: 129.99,
  currency: 'USD',
  
  // Additional context
  metadata: &#123;
    orderId: 'ORD-12345',
    products: ['product_a', 'product_b'],
    category: 'electronics'
  &#125;,
  
  timestamp: new Date().toISOString()
&#125;);

// Get conversion analytics
const conversionAnalytics = await omx.email.getConversionAnalytics(&#123;
  campaigns: ['welcome_campaign_2024'],
  events: ['purchase', 'signup'],
  timeRange: '30d',
  
  breakdown: &#123;
    by: ['campaign', 'email_template', 'user_segment'],
    includeAttribution: true
  &#125;
&#125;);

console.log(conversionAnalytics);
// &#123;
//   summary: &#123;
//     totalConversions: 156,
//     totalRevenue: 18750.50,
//     conversionRate: 0.012,
//     revenuePerEmail: 1.50,
//     avgOrderValue: 120.20,
//     roas: 12.5 // Return on ad spend
//   &#125;,
//   
//   attribution: &#123;
//     direct: &#123; conversions: 89, revenue: 10680.30 &#125;,
//     assisted: &#123; conversions: 67, revenue: 8070.20 &#125;
//   &#125;,
//   
//   breakdown: &#123;
//     by_campaign: [
//       &#123;
//         campaign: 'welcome_campaign_2024',
//         conversions: 89,
//         revenue: 10750.30,
//         conversionRate: 0.015
//       &#125;
//     ],
//     
//     by_template: [
//       &#123;
//         template: 'welcome_email',
//         conversions: 45,
//         revenue: 5400.20,
//         conversionRate: 0.018
//       &#125;
//     ]
//   &#125;
// &#125;

// Revenue attribution analysis
const attributionAnalysis = await omx.email.getAttributionAnalysis(&#123;
  timeRange: '90d',
  models: ['first_touch', 'last_touch', 'linear', 'time_decay'],
  includeAssisted: true
&#125;);

Real-time Monitoring

Monitor email performance in real-time with alerts and dashboards:

// Set up real-time monitoring
const monitor = await omx.email.createMonitor(&#123;
  name: 'Email Performance Monitor',
  
  // Metrics to monitor
  metrics: [
    &#123; name: 'deliveryRate', threshold: &#123; min: 0.95 &#125; &#125;,
    &#123; name: 'bounceRate', threshold: &#123; max: 0.05 &#125; &#125;,
    &#123; name: 'complaintRate', threshold: &#123; max: 0.001 &#125; &#125;,
    &#123; name: 'openRate', threshold: &#123; min: 0.20 &#125; &#125;,
    &#123; name: 'clickRate', threshold: &#123; min: 0.02 &#125; &#125;
  ],
  
  // Time windows for analysis
  windows: ['1h', '6h', '24h'],
  
  // Alert configuration
  alerts: &#123;
    email: &#123;
      recipients: ['admin@yourapp.com'],
      severity: ['critical', 'warning']
    &#125;,
    webhook: &#123;
      url: 'https://yourapp.com/alerts/email',
      secret: 'alert_webhook_secret'
    &#125;,
    slack: &#123;
      channel: '#email-alerts',
      webhook: process.env.SLACK_WEBHOOK_URL
    &#125;
  &#125;
&#125;);

// Real-time event stream
const eventStream = omx.email.createEventStream(&#123;
  events: ['delivered', 'opened', 'clicked', 'bounced', 'complained'],
  
  filters: &#123;
    campaigns: ['welcome_campaign_2024'],
    timeWindow: '1h'
  &#125;
&#125;);

eventStream.on('event', (event) =&gt; &#123;
  // Update real-time dashboard
  updateDashboard(event);
  
  // Check for anomalies
  if (detectAnomaly(event)) &#123;
    triggerAlert(event);
  &#125;
&#125;);

// Get real-time metrics
const realtimeMetrics = await omx.email.getRealtimeMetrics(&#123;
  timeWindow: '1h',
  granularity: '5m'
&#125;);

console.log('Last hour metrics:', realtimeMetrics);
// &#123;
//   timestamp: '2024-01-15T15:00:00Z',
//   sent: 1250,
//   delivered: 1205,
//   opened: 482,
//   clicked: 73,
//   bounced: 45,
//   complaints: 2,
//   
//   rates: &#123;
//     delivery: 0.964,
//     open: 0.40,
//     click: 0.058,
//     bounce: 0.036,
//     complaint: 0.0016
//   &#125;,
//   
//   trends: &#123;
//     delivery: 'stable',
//     open: 'increasing',
//     click: 'stable',
//     bounce: 'decreasing'
//   &#125;
// &#125;

// Anomaly detection
const anomalies = await omx.email.detectAnomalies(&#123;
  metrics: ['openRate', 'clickRate', 'bounceRate'],
  sensitivity: 'medium',
  timeRange: '7d'
&#125;);

if (anomalies.length &gt; 0) &#123;
  console.log('Detected anomalies:', anomalies);
  // [
  //   &#123;
  //     metric: 'bounceRate',
  //     value: 0.087,
  //     expected: 0.025,
  //     severity: 'high',
  //     timestamp: '2024-01-15T14:30:00Z'
  //   &#125;
  // ]
&#125;

Advanced Analytics

Leverage advanced analytics features for deeper insights:

// Cohort analysis
const cohortAnalysis = await omx.email.getCohortAnalysis(&#123;
  cohortBy: 'signup_month',
  metric: 'engagement_score',
  timeRange: '12m',
  
  cohortDefinition: &#123;
    period: 'month',
    size: 'auto'
  &#125;
&#125;);

// Heat map analysis
const heatMap = await omx.email.getHeatMapAnalysis(&#123;
  dimension: 'send_time',
  metric: 'open_rate',
  granularity: 'hour',
  
  filters: &#123;
    campaigns: ['newsletter'],
    userSegment: 'active_users',
    timeRange: '30d'
  &#125;
&#125;);

// Funnel analysis
const funnelAnalysis = await omx.email.getFunnelAnalysis(&#123;
  steps: [
    &#123; name: 'sent', event: 'email_sent' &#125;,
    &#123; name: 'delivered', event: 'email_delivered' &#125;,
    &#123; name: 'opened', event: 'email_opened' &#125;,
    &#123; name: 'clicked', event: 'email_clicked' &#125;,
    &#123; name: 'converted', event: 'purchase' &#125;
  ],
  
  breakdown: &#123;
    by: ['campaign', 'user_segment', 'device'],
    timeRange: '30d'
  &#125;
&#125;);

console.log('Funnel conversion rates:', funnelAnalysis.conversionRates);
// &#123;
//   'sent_to_delivered': 0.974,
//   'delivered_to_opened': 0.412,
//   'opened_to_clicked': 0.145,
//   'clicked_to_converted': 0.089
// &#125;

// Predictive analytics
const predictions = await omx.email.getPredictions(&#123;
  model: 'engagement_prediction',
  
  predictions: [
    &#123; type: 'open_probability', userId: 'user_123' &#125;,
    &#123; type: 'click_probability', userId: 'user_123' &#125;,
    &#123; type: 'unsubscribe_risk', userId: 'user_123' &#125;,
    &#123; type: 'lifetime_value', userId: 'user_123' &#125;
  ],
  
  features: &#123;
    includeHistorical: true,
    includeBehavioral: true,
    includeDemographic: true
  &#125;
&#125;);

// A/B test analysis
const abTestResults = await omx.email.getABTestResults('test_123', &#123;
  metrics: ['open_rate', 'click_rate', 'conversion_rate'],
  confidenceLevel: 0.95,
  
  analysis: &#123;
    includeSegmentation: true,
    includeStatisticalSignificance: true,
    includeEffectSize: true
  &#125;
&#125;);

console.log('A/B Test Results:', abTestResults);
// &#123;
//   testId: 'test_123',
//   status: 'completed',
//   winner: 'variant_b',
//   
//   results: &#123;
//     control: &#123;
//       participants: 1000,
//       openRate: 0.384,
//       clickRate: 0.056,
//       conversionRate: 0.012
//     &#125;,
//     variant_b: &#123;
//       participants: 1000,
//       openRate: 0.421,
//       clickRate: 0.074,
//       conversionRate: 0.018
//     &#125;
//   &#125;,
//   
//   significance: &#123;
//     openRate: &#123; pValue: 0.032, significant: true &#125;,
//     clickRate: &#123; pValue: 0.018, significant: true &#125;,
//     conversionRate: &#123; pValue: 0.089, significant: false &#125;
//   &#125;,
//   
//   recommendation: 'Deploy variant B - shows 9.6% improvement in open rate'
// &#125;

Data Export and Integration

Export tracking data and integrate with external analytics platforms:

// Export analytics data
const exportRequest = await omx.email.exportData(&#123;
  type: 'campaign_analytics',
  format: 'csv', // 'csv', 'json', 'excel'
  
  filters: &#123;
    campaigns: ['welcome_campaign_2024'],
    dateRange: &#123; start: '2024-01-01', end: '2024-01-31' &#125;
  &#125;,
  
  fields: [
    'messageId',
    'recipient',
    'sentAt',
    'deliveredAt',
    'openedAt',
    'clickedAt',
    'conversions'
  ],
  
  delivery: &#123;
    method: 'download', // 'download', 'email', 's3'
    email: 'analytics@yourapp.com'
  &#125;
&#125;);

// Integration with Google Analytics
await omx.email.integrateGA4(&#123;
  measurementId: 'G-XXXXXXXXXX',
  apiSecret: 'api_secret_here',
  
  eventMapping: &#123;
    'email_sent': 'email_campaign_sent',
    'email_opened': 'email_campaign_opened',
    'email_clicked': 'email_campaign_clicked'
  &#125;,
  
  customDimensions: &#123;
    'campaign_name': 'custom_dimension_1',
    'user_segment': 'custom_dimension_2'
  &#125;
&#125;);

// Integration with Mixpanel
await omx.email.integrateMixpanel(&#123;
  projectToken: 'mixpanel_token',
  
  eventTracking: &#123;
    trackOpens: true,
    trackClicks: true,
    trackConversions: true,
    
    userProperties: ['email_engagement_score', 'preferred_send_time']
  &#125;
&#125;);

// Custom webhook for real-time data streaming
await omx.email.setupDataWebhook(&#123;
  url: 'https://yourapp.com/email-data-webhook',
  events: ['delivered', 'opened', 'clicked', 'converted'],
  
  format: &#123;
    type: 'json',
    batchSize: 100,
    batchTimeout: 30 // seconds
  &#125;,
  
  authentication: &#123;
    type: 'hmac',
    secret: 'webhook_secret_key'
  &#125;
&#125;);

// Real-time data streaming to your data warehouse
const dataStream = omx.email.createDataStream(&#123;
  destination: &#123;
    type: 'bigquery',
    projectId: 'your-project',
    dataset: 'email_analytics',
    table: 'events'
  &#125;,
  
  schema: &#123;
    messageId: 'STRING',
    event: 'STRING',
    timestamp: 'TIMESTAMP',
    userId: 'STRING',
    campaignId: 'STRING',
    metadata: 'JSON'
  &#125;
&#125;);

Best Practices

Privacy Compliance: Respect user privacy and comply with GDPR/CCPA regulations
Data Retention: Implement appropriate data retention policies
Accurate Attribution: Use proper attribution windows for conversion tracking
Regular Monitoring: Set up alerts for key metrics and anomalies
Segmentation Analysis: Analyze performance across different user segments
Actionable Insights: Focus on metrics that drive business decisions

Email Tracking