CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-sendgrid--mail

Twilio SendGrid NodeJS mail service for sending transactional and marketing emails with templates, attachments, and advanced delivery features.

—

Pending
Overview
Eval results
Files

tracking-analytics.mddocs/

Tracking and Analytics

Tracking and analytics provide comprehensive email engagement monitoring including open tracking, click tracking, subscription management, and Google Analytics integration. These features help measure email performance and user engagement.

Capabilities

Click Tracking

Monitor when recipients click links in your emails with detailed click analytics.

// Click tracking settings
interface ClickTrackingSettings {
  enable?: boolean;      // Enable/disable click tracking
  enableText?: boolean;  // Enable click tracking in text emails
}

// Usage in tracking settings
const msg = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Email with Click Tracking',
  html: '<p>Visit our <a href="https://example.com">website</a>!</p>',
  trackingSettings: {
    clickTracking: {
      enable: true,
      enableText: true
    }
  }
};

Usage Examples:

// Basic click tracking
const newsletterMsg = {
  to: 'subscriber@example.com',
  from: 'newsletter@example.com',
  subject: 'March Newsletter - Click to Read More',
  html: `
    <div>
      <h1>March Newsletter</h1>
      <p>Check out our latest features:</p>
      <ul>
        <li><a href="https://example.com/feature1">New Dashboard</a></li>
        <li><a href="https://example.com/feature2">API Improvements</a></li>
        <li><a href="https://example.com/feature3">Mobile App Updates</a></li>
      </ul>
      <p><a href="https://example.com/unsubscribe">Unsubscribe</a></p>
    </div>
  `,
  text: `
    March Newsletter
    
    Check out our latest features:
    - New Dashboard: https://example.com/feature1
    - API Improvements: https://example.com/feature2
    - Mobile App Updates: https://example.com/feature3
    
    Unsubscribe: https://example.com/unsubscribe
  `,
  trackingSettings: {
    clickTracking: {
      enable: true,
      enableText: true  // Track clicks in plain text version too
    }
  }
};

// Selective click tracking (HTML only)
const transactionalMsg = {
  to: 'customer@example.com',
  from: 'orders@example.com',
  subject: 'Order Confirmation #12345',
  html: `
    <div>
      <h2>Order Confirmed</h2>
      <p>Your order #12345 has been confirmed.</p>
      <p><a href="https://example.com/orders/12345">View Order Details</a></p>
      <p><a href="https://example.com/account">Manage Account</a></p>
    </div>
  `,
  trackingSettings: {
    clickTracking: {
      enable: true,
      enableText: false  // Only track HTML clicks for transactional emails
    }
  }
};

Open Tracking

Track when recipients open your emails using invisible tracking pixels.

// Open tracking settings
interface OpenTrackingSettings {
  enable?: boolean;           // Enable/disable open tracking
  substitutionTag?: string;   // Custom substitution tag for tracking pixel placement
}

// Usage in tracking settings
const msg = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Email with Open Tracking',
  html: '<p>This email tracks opens automatically.</p>',
  trackingSettings: {
    openTracking: {
      enable: true,
      substitutionTag: '%open-track%'
    }
  }
};

Usage Examples:

// Basic open tracking
const welcomeMsg = {
  to: 'newuser@example.com',
  from: 'welcome@example.com',
  subject: 'Welcome to Our Platform!',
  html: `
    <div>
      <h1>Welcome!</h1>
      <p>We're excited to have you join our platform.</p>
      <p>Get started by exploring these features:</p>
      <ul>
        <li>Create your first project</li>
        <li>Invite team members</li>
        <li>Customize your dashboard</li>
      </ul>
    </div>
  `,
  trackingSettings: {
    openTracking: {
      enable: true
    }
  }
};

// Custom tracking pixel placement
const customTrackingMsg = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Email with Custom Tracking',
  html: `
    <div>
      <h1>Newsletter</h1>
      <p>Here's our latest content...</p>
      %open-track%
      <footer>
        <p>© 2024 Example Corp</p>
      </footer>
    </div>
  `,
  trackingSettings: {
    openTracking: {
      enable: true,
      substitutionTag: '%open-track%'  // Pixel placed at specified location
    }
  }
};

// Disable open tracking for sensitive emails
const sensitiveMsg = {
  to: 'user@example.com',
  from: 'security@example.com',
  subject: 'Password Reset Request',
  html: '<p>Click the link below to reset your password...</p>',
  trackingSettings: {
    openTracking: {
      enable: false  // No open tracking for security emails
    }
  }
};

Subscription Tracking

Provide automatic unsubscribe functionality with customizable unsubscribe content.

// Subscription tracking settings
interface SubscriptionTrackingSettings {
  enable?: boolean;           // Enable/disable subscription tracking
  text?: string;             // Plain text unsubscribe content
  html?: string;             // HTML unsubscribe content
  substitutionTag?: string;   // Custom substitution tag for unsubscribe placement
}

// Usage in tracking settings
const msg = {
  to: 'subscriber@example.com',
  from: 'newsletter@example.com',
  subject: 'Monthly Newsletter',
  text: 'Newsletter content...',
  trackingSettings: {
    subscriptionTracking: {
      enable: true,
      text: 'Unsubscribe: https://example.com/unsubscribe',
      html: '<p><a href="https://example.com/unsubscribe">Unsubscribe</a></p>'
    }
  }
};

Usage Examples:

// Basic subscription tracking
const marketingMsg = {
  to: 'customer@example.com',
  from: 'marketing@example.com',
  subject: 'Special Offers This Week',
  html: `
    <div>
      <h2>This Week's Special Offers</h2>
      <div>
        <h3>50% Off Premium Plans</h3>
        <p>Upgrade now and save big on our premium features.</p>
        <a href="https://example.com/upgrade">Upgrade Now</a>
      </div>
    </div>
  `,
  text: `
    This Week's Special Offers
    
    50% Off Premium Plans
    Upgrade now and save big on our premium features.
    Upgrade: https://example.com/upgrade
  `,
  trackingSettings: {
    subscriptionTracking: {
      enable: true,
      text: 'To unsubscribe from marketing emails: https://example.com/unsubscribe',
      html: '<p style="font-size: 12px; color: #666;"><a href="https://example.com/unsubscribe">Unsubscribe</a> from marketing emails</p>'
    }
  }
};

// Custom unsubscribe placement
const customUnsubscribeMsg = {
  to: 'subscriber@example.com',
  from: 'newsletter@example.com',
  subject: 'Weekly Newsletter #47',
  html: `
    <div>
      <header>
        <h1>Weekly Newsletter</h1>
        <p>Issue #47 - March 15, 2024</p>
      </header>
      
      <main>
        <article>
          <h2>Feature Article</h2>
          <p>This week we're covering...</p>
        </article>
      </main>
      
      <footer>
        <p>Thanks for reading!</p>
        %unsubscribe%
        <p>© 2024 Example Corp</p>
      </footer>
    </div>
  `,
  trackingSettings: {
    subscriptionTracking: {
      enable: true,
      substitutionTag: '%unsubscribe%',
      html: '<p><a href="https://example.com/unsubscribe">Click here to unsubscribe</a></p>'
    }
  }
};

// Different unsubscribe text for different content types
const dualContentMsg = {
  to: 'user@example.com',
  from: 'updates@example.com',
  subject: 'Product Updates',
  html: `
    <div>
      <h2>Latest Product Updates</h2>
      <p>Here's what's new in our latest release...</p>
    </div>
  `,
  text: `
    Latest Product Updates
    
    Here's what's new in our latest release...
  `,
  trackingSettings: {
    subscriptionTracking: {
      enable: true,
      text: 'Unsubscribe: https://example.com/unsubscribe?type=text',
      html: '<div style="text-align: center; margin-top: 20px;"><a href="https://example.com/unsubscribe?type=html" style="color: #666; font-size: 12px;">Unsubscribe from these emails</a></div>'
    }
  }
};

Google Analytics Integration

Integrate email campaigns with Google Analytics for comprehensive tracking across your website.

// Google Analytics tracking settings
interface GoogleAnalyticsSettings {
  enable?: boolean;      // Enable/disable Google Analytics tracking
  utmSource?: string;    // UTM source parameter
  utmMedium?: string;    // UTM medium parameter  
  utmTerm?: string;      // UTM term parameter
  utmContent?: string;   // UTM content parameter
  utmCampaign?: string;  // UTM campaign parameter
}

// Usage in tracking settings
const msg = {
  to: 'recipient@example.com',
  from: 'marketing@example.com',
  subject: 'Spring Campaign Launch',
  html: '<p>Visit our <a href="https://example.com">website</a>!</p>',
  trackingSettings: {
    ganalytics: {
      enable: true,
      utmSource: 'sendgrid',
      utmMedium: 'email',
      utmCampaign: 'spring-2024',
      utmContent: 'launch-announcement'
    }
  }
};

Usage Examples:

// Campaign tracking with Google Analytics
const campaignMsg = {
  to: 'customer@example.com',
  from: 'campaigns@example.com',
  subject: 'Summer Sale - Up to 70% Off',
  html: `
    <div>
      <h1>Summer Sale is Here!</h1>
      <p>Save up to 70% on selected items.</p>
      <div>
        <a href="https://example.com/sale/clothing">Shop Clothing</a> |
        <a href="https://example.com/sale/electronics">Shop Electronics</a> |
        <a href="https://example.com/sale/home">Shop Home & Garden</a>
      </div>
      <p><a href="https://example.com/sale">View All Sale Items</a></p>
    </div>
  `,
  trackingSettings: {
    ganalytics: {
      enable: true,
      utmSource: 'newsletter',
      utmMedium: 'email',
      utmCampaign: 'summer-sale-2024',
      utmContent: 'main-announcement',
      utmTerm: 'summer-sale'
    }
  }
};

// Product-specific tracking
const productMsg = {
  to: 'subscriber@example.com',
  from: 'products@example.com',
  subject: 'New Product Launch - Smart Home Hub',
  html: `
    <div>
      <h2>Introducing the Smart Home Hub</h2>
      <img src="https://example.com/images/smart-hub.jpg" alt="Smart Home Hub">
      <p>Control all your smart devices from one place.</p>
      <a href="https://example.com/products/smart-hub">Learn More</a>
      <a href="https://example.com/products/smart-hub/buy">Buy Now</a>
    </div>
  `,
  trackingSettings: {
    ganalytics: {
      enable: true,
      utmSource: 'product-launch',
      utmMedium: 'email',
      utmCampaign: 'smart-hub-launch',
      utmContent: 'hero-announcement',
      utmTerm: 'smart-home'
    }
  }
};

// A/B testing with different UTM content
const abTestMsgA = {
  to: 'group-a@example.com',
  from: 'test@example.com',
  subject: 'Try Our New Feature - Version A',
  html: '<div><h2>New Feature Available</h2><p>Basic description...</p><a href="https://example.com/feature">Try Now</a></div>',
  trackingSettings: {
    ganalytics: {
      enable: true,
      utmSource: 'email-test',
      utmMedium: 'email',
      utmCampaign: 'feature-launch',
      utmContent: 'version-a-basic',
      utmTerm: 'new-feature'
    }
  }
};

const abTestMsgB = {
  to: 'group-b@example.com',
  from: 'test@example.com',
  subject: 'Try Our New Feature - Version B',
  html: '<div><h2>Revolutionary New Feature!</h2><p>Detailed benefits...</p><a href="https://example.com/feature">Get Started Today</a></div>',
  trackingSettings: {
    ganalytics: {
      enable: true,
      utmSource: 'email-test',
      utmMedium: 'email',
      utmCampaign: 'feature-launch',
      utmContent: 'version-b-detailed',
      utmTerm: 'new-feature'
    }
  }
};

Complete Tracking Configuration

Combine all tracking features for comprehensive email analytics.

// Complete tracking settings interface
interface TrackingSettings {
  clickTracking?: ClickTrackingSettings;
  openTracking?: OpenTrackingSettings;
  subscriptionTracking?: SubscriptionTrackingSettings;
  ganalytics?: GoogleAnalyticsSettings;
}

// Usage with all tracking features enabled
const msg = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Fully Tracked Email',
  html: 'Email content with tracking...',
  trackingSettings: {
    clickTracking: { enable: true, enableText: true },
    openTracking: { enable: true },
    subscriptionTracking: { enable: true },
    ganalytics: { enable: true, utmCampaign: 'campaign-name' }
  }
};

Usage Examples:

// Complete newsletter with all tracking
const comprehensiveNewsletter = {
  to: 'subscriber@example.com',
  from: 'newsletter@example.com',
  subject: 'Monthly Newsletter - March 2024',
  html: `
    <div>
      <header>
        <h1>March Newsletter</h1>
        <p>Your monthly dose of updates and insights</p>
      </header>
      
      <main>
        <section>
          <h2>Feature Spotlight</h2>
          <p>This month we're highlighting our new dashboard...</p>
          <a href="https://example.com/features/dashboard">Explore Dashboard</a>
        </section>
        
        <section>
          <h2>Customer Success Story</h2>
          <p>See how Company XYZ increased their productivity by 300%...</p>
          <a href="https://example.com/case-studies/xyz">Read Full Story</a>
        </section>
        
        <section>
          <h2>Upcoming Events</h2>
          <ul>
            <li><a href="https://example.com/events/webinar1">Product Demo Webinar - March 20</a></li>
            <li><a href="https://example.com/events/conference">Annual Conference - April 15</a></li>
          </ul>
        </section>
      </main>
      
      <footer>
        <p>Follow us on social media:</p>
        <a href="https://twitter.com/example">Twitter</a> |
        <a href="https://linkedin.com/company/example">LinkedIn</a>
      </footer>
    </div>
  `,
  text: `
    March Newsletter
    Your monthly dose of updates and insights
    
    Feature Spotlight
    This month we're highlighting our new dashboard...
    Explore Dashboard: https://example.com/features/dashboard
    
    Customer Success Story  
    See how Company XYZ increased their productivity by 300%...
    Read Full Story: https://example.com/case-studies/xyz
    
    Upcoming Events
    - Product Demo Webinar - March 20: https://example.com/events/webinar1
    - Annual Conference - April 15: https://example.com/events/conference
    
    Follow us:
    Twitter: https://twitter.com/example
    LinkedIn: https://linkedin.com/company/example
  `,
  trackingSettings: {
    clickTracking: {
      enable: true,
      enableText: true
    },
    openTracking: {
      enable: true
    },
    subscriptionTracking: {
      enable: true,
      text: 'Unsubscribe from newsletters: https://example.com/unsubscribe',
      html: '<p style="text-align: center; font-size: 12px; color: #888;"><a href="https://example.com/unsubscribe">Unsubscribe</a> | <a href="https://example.com/preferences">Update Preferences</a></p>'
    },
    ganalytics: {
      enable: true,
      utmSource: 'newsletter',
      utmMedium: 'email',
      utmCampaign: 'monthly-newsletter',
      utmContent: 'march-2024',
      utmTerm: 'subscriber'
    }
  }
};

// Transactional email with selective tracking
const orderConfirmation = {
  to: 'customer@example.com',
  from: 'orders@example.com',
  subject: 'Order Confirmation #ORDER-2024-001234',
  html: `
    <div>
      <h2>Order Confirmed!</h2>
      <p>Thank you for your order. Here are the details:</p>
      
      <div>
        <h3>Order #ORDER-2024-001234</h3>
        <p>Total: $129.99</p>
        <p>Estimated delivery: March 18, 2024</p>
      </div>
      
      <p><a href="https://example.com/orders/ORDER-2024-001234">View Order Details</a></p>
      <p><a href="https://example.com/account">Manage Account</a></p>
    </div>
  `,
  trackingSettings: {
    clickTracking: {
      enable: true,
      enableText: false  // Only HTML tracking for transactional
    },
    openTracking: {
      enable: true
    },
    subscriptionTracking: {
      enable: false  // No unsubscribe for transactional emails
    },
    ganalytics: {
      enable: true,
      utmSource: 'transactional',
      utmMedium: 'email',
      utmCampaign: 'order-confirmation',
      utmContent: 'order-details'
    }
  }
};

Analytics Best Practices

Tracking Strategy

  1. Segment tracking by email type: Use different UTM parameters for transactional vs. marketing emails
  2. Consistent naming conventions: Establish clear patterns for campaign names and content identifiers
  3. A/B test tracking parameters: Use UTM content to differentiate test variations
  4. Privacy considerations: Be transparent about tracking in your privacy policy

Performance Monitoring

  1. Monitor open rates: Track engagement trends over time
  2. Analyze click patterns: Identify most popular content and links
  3. Conversion tracking: Connect email clicks to website conversions
  4. Unsubscribe analysis: Monitor subscription health and content performance

Compliance and Privacy

  1. Honor unsubscribe requests: Process unsubscribes promptly and completely
  2. Provide clear opt-out: Make unsubscribe links easy to find and use
  3. GDPR compliance: Consider tracking implications for EU recipients
  4. Data retention: Define policies for how long to retain tracking data

Install with Tessl CLI

npx tessl i tessl/npm-sendgrid--mail

docs

advanced-delivery.md

attachments-content.md

email-service.md

index.md

message-construction.md

templates-personalization.md

tracking-analytics.md

tile.json