Email Queue Pattern | Bootspring Docs

Process emails asynchronously with queues for reliable delivery, retries, and scheduled sending.

Overview#

Email queues decouple email sending from your application's request cycle. This improves response times, enables scheduled delivery, and provides built-in retry logic for failed sends.

When to use:

High-volume email sending
Scheduled emails (reminders, digests)
Newsletter distribution
Any email that should not block user requests
When you need retry logic for failures

Key features:

Database-backed queue
Priority levels
Scheduled delivery
Automatic retries
Batch processing
Status tracking

Code Example#

Database Schema#

// prisma/schema.prisma
model EmailQueue {
  id          String   @id @default(cuid())
  to          String
  subject     String
  template    String
  data        String   // JSON stringified template data
  status      EmailStatus @default(PENDING)
  priority    Int      @default(0)
  scheduledAt DateTime @default(now())
  sentAt      DateTime?
  openedAt    DateTime?
  error       String?
  retryCount  Int      @default(0)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

enum EmailStatus {
  PENDING
  PROCESSING
  SENT
  FAILED
}

Queue Email Function#

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

interface QueuedEmail {
  to: string
  subject: string
  template: string
  data: Record<string, any>
  scheduledAt?: Date
  priority?: number
}

export async function queueEmail(email: QueuedEmail) {
  return prisma.emailQueue.create({
    data: {
      to: email.to,
      subject: email.subject,
      template: email.template,
      data: JSON.stringify(email.data),
      scheduledAt: email.scheduledAt ?? new Date(),
      priority: email.priority ?? 0,
      status: 'PENDING'
    }
  })
}

// Queue multiple emails
export async function queueEmails(emails: QueuedEmail[]) {
  return prisma.emailQueue.createMany({
    data: emails.map(email => ({
      to: email.to,
      subject: email.subject,
      template: email.template,
      data: JSON.stringify(email.data),
      scheduledAt: email.scheduledAt ?? new Date(),
      priority: email.priority ?? 0,
      status: 'PENDING' as const
    }))
  })
}

Process Queue#

// lib/email-queue.ts
import { templates } from '@/emails'

export async function processEmailQueue() {
  // Get pending emails that are ready to send
  const emails = await prisma.emailQueue.findMany({
    where: {
      status: 'PENDING',
      scheduledAt: { lte: new Date() }
    },
    orderBy: [
      { priority: 'desc' },
      { scheduledAt: 'asc' }
    ],
    take: 10
  })

  for (const email of emails) {
    try {
      // Mark as processing
      await prisma.emailQueue.update({
        where: { id: email.id },
        data: { status: 'PROCESSING' }
      })

      // Render template
      const Template = templates[email.template as keyof typeof templates]
      if (!Template) {
        throw new Error(`Template not found: ${email.template}`)
      }

      const html = await render(Template(JSON.parse(email.data)))

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

      // Mark as sent
      await prisma.emailQueue.update({
        where: { id: email.id },
        data: { status: 'SENT', sentAt: new Date() }
      })
    } catch (error) {
      // Mark as failed
      await prisma.emailQueue.update({
        where: { id: email.id },
        data: {
          status: 'FAILED',
          error: error instanceof Error ? error.message : 'Unknown error',
          retryCount: { increment: 1 }
        }
      })
    }
  }
}

Cron Job for Processing#

// app/api/cron/process-emails/route.ts
import { processEmailQueue } from '@/lib/email-queue'
import { NextRequest, NextResponse } from 'next/server'

export async function GET(request: NextRequest) {
  // Verify cron secret
  const authHeader = request.headers.get('authorization')
  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  await processEmailQueue()

  return NextResponse.json({ success: true })
}

// vercel.json
{
  "crons": [{
    "path": "/api/cron/process-emails",
    "schedule": "* * * * *"
  }]
}

Retry Logic#

// lib/email-queue.ts
const MAX_RETRIES = 3
const RETRY_DELAYS = [60, 300, 900] // 1min, 5min, 15min (in seconds)

export async function retryFailedEmails() {
  const failedEmails = await prisma.emailQueue.findMany({
    where: {
      status: 'FAILED',
      retryCount: { lt: MAX_RETRIES }
    }
  })

  for (const email of failedEmails) {
    const retryDelay = RETRY_DELAYS[email.retryCount] ?? RETRY_DELAYS[RETRY_DELAYS.length - 1]
    const nextRetry = new Date(Date.now() + retryDelay * 1000)

    await prisma.emailQueue.update({
      where: { id: email.id },
      data: {
        status: 'PENDING',
        scheduledAt: nextRetry
      }
    })
  }
}

Priority Queue#

// lib/email-queue.ts
export const EMAIL_PRIORITY = {
  CRITICAL: 100,  // Password resets, 2FA codes
  HIGH: 75,       // Order confirmations, payment receipts
  NORMAL: 50,     // Notifications, updates
  LOW: 25,        // Marketing, recommendations
  BULK: 0         // Newsletters, digests
} as const

// Usage
await queueEmail({
  to: user.email,
  subject: 'Reset your password',
  template: 'password-reset',
  data: { resetUrl },
  priority: EMAIL_PRIORITY.CRITICAL
})

await queueEmail({
  to: user.email,
  subject: 'Weekly digest',
  template: 'digest',
  data: { posts },
  priority: EMAIL_PRIORITY.LOW,
  scheduledAt: nextSunday()
})

// lib/email-queue.ts
export async function queueBatchEmails(
  recipients: string[],
  template: string,
  subject: string,
  getData: (email: string) => Record<string, any>
) {
  const emails = recipients.map(to => ({
    to,
    subject,
    template,
    data: JSON.stringify(getData(to)),
    scheduledAt: new Date(),
    priority: EMAIL_PRIORITY.BULK,
    status: 'PENDING' as const
  }))

  // Batch insert for efficiency
  await prisma.emailQueue.createMany({ data: emails })
}

// Usage - Newsletter
const subscribers = await prisma.subscriber.findMany({
  where: { active: true },
  select: { email: true }
})

await queueBatchEmails(
  subscribers.map(s => s.email),
  'newsletter',
  'Weekly Newsletter - March 2024',
  (email) => ({
    email,
    unsubscribeUrl: generateUnsubscribeUrl(email)
  })
)

Queue Status Dashboard#

// lib/email-queue.ts
export async function getQueueStats() {
  const [pending, processing, sent, failed] = await Promise.all([
    prisma.emailQueue.count({ where: { status: 'PENDING' } }),
    prisma.emailQueue.count({ where: { status: 'PROCESSING' } }),
    prisma.emailQueue.count({ where: { status: 'SENT' } }),
    prisma.emailQueue.count({ where: { status: 'FAILED' } })
  ])

  const recentFailures = await prisma.emailQueue.findMany({
    where: {
      status: 'FAILED',
      updatedAt: { gte: new Date(Date.now() - 24 * 60 * 60 * 1000) }
    },
    orderBy: { updatedAt: 'desc' },
    take: 10
  })

  return {
    counts: { pending, processing, sent, failed },
    total: pending + processing + sent + failed,
    recentFailures
  }
}

Usage Instructions#

Create database table: Add the EmailQueue model to your Prisma schema
Run migration: npx prisma db push or npx prisma migrate dev
Queue emails: Use queueEmail() instead of sending directly
Set up cron: Configure a cron job to process the queue
Monitor status: Build a dashboard to track queue health

Best Practices#

Use priorities - Critical emails (auth) should process before marketing
Set retry limits - Don't retry forever; mark as permanently failed
Implement backoff - Increase delay between retries
Monitor the queue - Alert when failed count is high
Clean up old records - Archive or delete old sent emails
Batch for newsletters - Use createMany for bulk inserts
Respect rate limits - Don't exceed provider limits
Log everything - Track sends for debugging

Transactional Email - Basic email sending
Email Templates - React Email components
Email Tracking - Open and click analytics