Email Tracking Pattern | Bootspring Docs

Track email opens and link clicks to measure engagement and improve email effectiveness.

Overview#

Email tracking helps you understand how recipients interact with your emails. Open tracking uses invisible pixels, while click tracking uses redirect URLs. This data enables better targeting and content optimization.

When to use:

Measuring email campaign effectiveness
A/B testing email content
Identifying engaged users
Triggering follow-up actions
Building engagement analytics

Key features:

Open tracking with pixels
Click tracking with redirects
Per-email analytics
Privacy-conscious options
Database storage

Code Example#

Database Schema#

// prisma/schema.prisma
model EmailQueue {
  id          String   @id @default(cuid())
  to          String
  subject     String
  template    String
  data        String
  status      EmailStatus @default(PENDING)
  sentAt      DateTime?
  openedAt    DateTime?
  createdAt   DateTime @default(now())

  clicks      EmailClick[]
}

model EmailClick {
  id        String   @id @default(cuid())
  emailId   String
  email     EmailQueue @relation(fields: [emailId], references: [id])
  link      String
  clickedAt DateTime @default(now())
  userAgent String?
  ip        String?

  @@index([emailId])
}

Open Tracking Endpoint#

// app/api/email/track/[id]/route.ts
import { prisma } from '@/lib/db'
import { NextRequest, NextResponse } from 'next/server'

// 1x1 transparent GIF pixel
const TRACKING_PIXEL = Buffer.from(
  'R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7',
  'base64'
)

export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const emailId = params.id

  // Record open (don't await to respond quickly)
  prisma.emailQueue.update({
    where: { id: emailId },
    data: {
      openedAt: new Date()
    }
  }).catch(console.error)

  // Return tracking pixel
  return new NextResponse(TRACKING_PIXEL, {
    headers: {
      'Content-Type': 'image/gif',
      'Cache-Control': 'no-store, no-cache, must-revalidate',
      'Pragma': 'no-cache'
    }
  })
}

Click Tracking Endpoint#

// app/api/email/click/[id]/route.ts
import { prisma } from '@/lib/db'
import { NextRequest, NextResponse } from 'next/server'

export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const emailId = params.id
  const searchParams = request.nextUrl.searchParams
  const url = searchParams.get('url')

  if (!url) {
    return NextResponse.redirect(new URL('/', request.url))
  }

  // Validate URL to prevent open redirect vulnerability
  let targetUrl: URL
  try {
    targetUrl = new URL(url)
    const allowedHosts = [
      process.env.NEXT_PUBLIC_APP_URL,
      // Add other allowed domains
    ].filter(Boolean).map(u => new URL(u!).host)

    if (!allowedHosts.includes(targetUrl.host)) {
      console.warn('Blocked redirect to:', targetUrl.host)
      return NextResponse.redirect(new URL('/', request.url))
    }
  } catch {
    return NextResponse.redirect(new URL('/', request.url))
  }

  // Record click
  await prisma.emailClick.create({
    data: {
      emailId,
      link: url,
      userAgent: request.headers.get('user-agent') ?? undefined,
      ip: request.ip ?? request.headers.get('x-forwarded-for') ?? undefined
    }
  }).catch(console.error)

  return NextResponse.redirect(targetUrl)
}

Add Tracking to Emails#

// lib/email/tracking.ts
const APP_URL = process.env.NEXT_PUBLIC_APP_URL

export function addTrackingPixel(emailId: string): string {
  return `<img src="${APP_URL}/api/email/track/${emailId}" width="1" height="1" style="display:none" alt="" />`
}

export function wrapLinksForTracking(
  html: string,
  emailId: string
): string {
  // Match href attributes
  const linkRegex = /href="(https?:\/\/[^"]+)"/g

  return html.replace(linkRegex, (match, url) => {
    // Don't track unsubscribe links
    if (url.includes('unsubscribe')) {
      return match
    }

    const trackingUrl = `${APP_URL}/api/email/click/${emailId}?url=${encodeURIComponent(url)}`
    return `href="${trackingUrl}"`
  })
}

export function addTracking(html: string, emailId: string): string {
  // Add tracking pixel before </body>
  let tracked = html.replace(
    '</body>',
    `${addTrackingPixel(emailId)}</body>`
  )

  // Wrap links
  tracked = wrapLinksForTracking(tracked, emailId)

  return tracked
}

Email Sending with Tracking#

// lib/email/service.ts
import { render } from '@react-email/render'
import { resend } from '@/lib/email'
import { prisma } from '@/lib/db'
import { addTracking } from './tracking'

export async function sendTrackedEmail(
  to: string,
  subject: string,
  Template: React.ComponentType<any>,
  props: any
) {
  // Create email record first
  const email = await prisma.emailQueue.create({
    data: {
      to,
      subject,
      template: Template.name,
      data: JSON.stringify(props),
      status: 'PENDING'
    }
  })

  try {
    // Render template
    let html = await render(Template(props))

    // Add tracking
    html = addTracking(html, email.id)

    // Send
    await resend.emails.send({
      from: `${process.env.EMAIL_FROM_NAME} <${process.env.EMAIL_FROM_ADDRESS}>`,
      to,
      subject,
      html
    })

    // Update status
    await prisma.emailQueue.update({
      where: { id: email.id },
      data: { status: 'SENT', sentAt: new Date() }
    })

    return email
  } catch (error) {
    await prisma.emailQueue.update({
      where: { id: email.id },
      data: {
        status: 'FAILED',
        error: error instanceof Error ? error.message : 'Unknown error'
      }
    })
    throw error
  }
}

Analytics Functions#

// lib/email/analytics.ts
import { prisma } from '@/lib/db'

export async function getEmailStats(emailId: string) {
  const email = await prisma.emailQueue.findUnique({
    where: { id: emailId },
    include: { clicks: true }
  })

  if (!email) return null

  return {
    id: email.id,
    to: email.to,
    subject: email.subject,
    sentAt: email.sentAt,
    opened: !!email.openedAt,
    openedAt: email.openedAt,
    clickCount: email.clicks.length,
    clicks: email.clicks.map(c => ({
      link: c.link,
      clickedAt: c.clickedAt
    }))
  }
}

export async function getCampaignStats(template: string, dateRange?: {
  from: Date
  to: Date
}) {
  const where = {
    template,
    status: 'SENT' as const,
    ...(dateRange && {
      sentAt: {
        gte: dateRange.from,
        lte: dateRange.to
      }
    })
  }

  const [total, opened, clicked] = await Promise.all([
    prisma.emailQueue.count({ where }),
    prisma.emailQueue.count({
      where: { ...where, openedAt: { not: null } }
    }),
    prisma.emailQueue.count({
      where: {
        ...where,
        clicks: { some: {} }
      }
    })
  ])

  return {
    total,
    opened,
    clicked,
    openRate: total > 0 ? (opened / total) * 100 : 0,
    clickRate: total > 0 ? (clicked / total) * 100 : 0,
    clickToOpenRate: opened > 0 ? (clicked / opened) * 100 : 0
  }
}

export async function getTopLinks(template: string, limit = 10) {
  const clicks = await prisma.emailClick.groupBy({
    by: ['link'],
    where: {
      email: { template }
    },
    _count: { link: true },
    orderBy: { _count: { link: 'desc' } },
    take: limit
  })

  return clicks.map(c => ({
    url: c.link,
    clicks: c._count.link
  }))
}

Privacy-Conscious Implementation#

// lib/email/tracking.ts

// Option to disable tracking per user
export async function shouldTrackEmail(userId: string): Promise<boolean> {
  const user = await prisma.user.findUnique({
    where: { id: userId },
    select: { emailTrackingEnabled: true }
  })

  return user?.emailTrackingEnabled ?? true
}

// Anonymize tracking data
export async function anonymizeTrackingData(olderThan: Date) {
  await prisma.emailClick.updateMany({
    where: {
      clickedAt: { lt: olderThan }
    },
    data: {
      ip: null,
      userAgent: null
    }
  })
}

// GDPR data export
export async function exportUserEmailData(userEmail: string) {
  const emails = await prisma.emailQueue.findMany({
    where: { to: userEmail },
    include: { clicks: true }
  })

  return emails.map(email => ({
    id: email.id,
    subject: email.subject,
    sentAt: email.sentAt,
    openedAt: email.openedAt,
    clicks: email.clicks.map(c => ({
      link: c.link,
      clickedAt: c.clickedAt
    }))
  }))
}

Usage Instructions#

Set up database: Add EmailQueue and EmailClick models
Create tracking endpoints: Implement pixel and click redirect routes
Wrap email content: Add tracking to HTML before sending
Record events: Track opens and clicks in the database
Analyze data: Build dashboards to visualize engagement

Best Practices#

Validate redirect URLs - Prevent open redirect vulnerabilities
Respond quickly - Don't slow down pixel/redirect responses
Handle errors silently - Don't break emails if tracking fails
Respect privacy - Offer opt-out and anonymize old data
Clean old data - Remove or anonymize tracking data over time
Don't track sensitive links - Skip unsubscribe and password reset links
Monitor for abuse - Watch for unusual patterns
Be transparent - Disclose tracking in privacy policy

Transactional Email - Basic email sending
Email Templates - React Email components
Email Queues - Background processing