Queueing Mail

Basic Queueing

When using the queue feature, mails can be delayed and processed asynchronously:

await sendMail(invoicePaidMail)
  .onQueue('mail')
  .delay(300) // 5 minutes delay
  .afterCommit()

This requires the @holo-js/queue package to be installed. If the configured queue connection uses an async driver, production also needs a supervised queue worker. See Deployment for host selection and Queue Workers for worker commands.

Queue Configuration

You can configure default queue settings in your mail configuration:

// config/mail.ts
export default defineMailConfig({
  default: 'smtp',
  queue: {
    connection: 'default',
    queue: 'mail',
    // Whether to delay dispatch until after database commits
    afterCommit: true
  },
  mailers: {
    smtp: {
      driver: 'smtp'
      // ... smtp config
    }
  }
})

Queue Options

Delayed Delivery

// Delay delivery by 1 hour
await sendMail(invoicePaidMail)
  .delay(60 * 60)

// Delay using a Date object
await sendMail(invoicePaidMail)
  .delay(new Date(Date.now() + 3600000))

Per-Mailer Queue Settings

You can set queue defaults per mailer:

// config/mail.ts
export default defineMailConfig({
  mailers: {
    smtp: {
      driver: 'smtp',
      queue: {
        connection: 'smtp-queue',
        queue: 'mail-high-priority'
      }
    }
  }
})

How Queueing Works

1. When .onQueue() is called, the mail is serialized and placed on a queue
2. A queue worker processes the job by:
   • Reconstructing the mail from the serialized data
   • Sending it using the configured mailer
3. If .afterCommit() is used, the mail is only queued after database transactions commit