Quick Start Example

Let's walk through a practical example of setting up a simple job queue. We'll create a task that sends a welcome email when a user signs up.

You might wonder: "Why not just send the email directly in the afterChange hook?"

Non-blocking: If your email service takes 2-3 seconds to send, your API response would be delayed. With jobs, the API returns immediately.
Resilience: If the email service is temporarily down, the hook would fail and potentially block the user creation. Jobs can retry automatically.
Scalability: As your app grows, you can move job processing to dedicated servers, keeping your API fast.
Monitoring: All jobs are tracked in the database, so you can see if emails failed and why.

Now let's build this example step by step.

Step 1: Define a Task

First, create a task in your payload.config.ts:

1import { buildConfig } from 'payload'
2
3export default buildConfig({
// ... other config
jobs: {
  tasks: [
    {
      slug: 'sendWelcomeEmail',
      retries: 3,
      inputSchema: [
        {
          name: 'userEmail',
          type: 'email',
          required: true,
        },
        {
          name: 'userName',
          type: 'text',
          required: true,
        },
      ],
      handler: async ({ input, req }) => {
        // Send email using your email service
        await req.payload.sendEmail({
          to: input.userEmail,
          subject: 'Welcome!',
          text: `Hi ${input.userName}, welcome to our platform!`,
        })
29
        return {
          output: {
            emailSent: true,
          },
        }
      },
    },
  ],
},
39})

This defines a reusable task with a unique slug, an inputSchema that validates and types the input data, and a handler function containing the work to be performed. The retries option ensures the task will automatically retry up to 3 times if it fails. Learn more about Tasks.

Step 2: Queue the Job trigger

1{
slug: 'users',
hooks: {
  afterChange: [
    async ({ req, doc, operation }) => {
      // Only send welcome email for new users
      if (operation === 'create') {
        await req.payload.jobs.queue({
          task: 'sendWelcomeEmail',
          input: {
            userEmail: doc.email,
            userName: doc.name,
          },
        })
      }
    },
  ],
},
// ... fields
20}

This uses payload.jobs.queue() to create a job instance from the task definition. The job is added to the queue immediately but runs asynchronously, so the API response returns right away without waiting for the email to send. Jobs are stored in the database as documents in the payload-jobs collection.

Step 3: Run the Jobs

1export default buildConfig({
// ... other config
jobs: {
  tasks: [
    /* ... */
  ],
  autoRun: [
    {
      cron: '*/5 * * * *', // Run every 5 minutes
    },
  ],
},
13})

The autoRun configuration automatically processes queued jobs on a schedule using cron syntax. In this example, Payload checks for pending jobs every 5 minutes and executes them. Alternatively, you can manually trigger job processing with payload.jobs.run() or use the API endpoint for serverless platforms.

That's it! Now when users sign up, a job is queued and will be processed within 5 minutes without blocking the API response.

Example 2: Recurring Scheduled Job

The previous example showed manual job queuing (jobs triggered by user actions). Now let's look at a job that runs automatically on a schedule without any user action.

We'll create a task that generates a daily analytics report every morning at 8 AM.

Why Use Scheduled Jobs?

Automated recurring tasks: No need to manually trigger them
Predictable timing: Reports, cleanups, syncs run at exact times
No manual intervention: Set it once and forget it

Step 1: Define a Task with Schedule

1import { buildConfig } from 'payload'
2
3export default buildConfig({
// ... other config
jobs: {
  tasks: [
    {
      slug: 'generateDailyReport',
9
      // This automatically queues a job every day at 8 AM
      schedule: [
        {
          cron: '0 8 * * *', // 8:00 AM daily
          queue: 'reports', // Put it in the 'reports' queue
        },
      ],
17
      inputSchema: [],
19
      outputSchema: [
        {
          name: 'reportId',
          type: 'text',
        },
      ],
26
      handler: async ({ req }) => {
        // Generate the report
        const yesterday = new Date()
        yesterday.setDate(yesterday.getDate() - 1)
31
        const analytics = await req.payload.find({
          collection: 'analytics',
          where: {
            createdAt: {
              greater_than_equal: yesterday.toISOString(),
            },
          },
        })
40
        // Save the report
        const report = await req.payload.create({
          collection: 'reports',
          data: {
            date: new Date().toISOString(),
            totalEvents: analytics.totalDocs,
            summary: `Generated report for ${yesterday.toDateString()}`,
          },
        })
50
        return {
          output: {
            reportId: report.id,
          },
        }
      },
    },
  ],
},
60})

The schedule property defines when this job should run (every day at 8 AM).

Step 2: Configure the Job Runner

To actually queue and execute scheduled jobs, you need to configure the autoRun property. This handles both queuing jobs based on their schedule and running them:

1export default buildConfig({
// ... other config
jobs: {
  tasks: [
    /* task from step 1 */
  ],
7
  // This processes jobs from the 'reports' queue
  autoRun: [
    {
      cron: '* * * * *', // Check every minute
      queue: 'reports', // Process 'reports' queue
      limit: 10,
    },
  ],
},
17})

How It Works

Here's the complete flow:

At 8:00 AM: The schedule configuration automatically queues a new job in the 'reports' queue
Within 1 minute: The autoRun cron checks the 'reports' queue and finds the job
Execution: The job runs and generates the report
The next day: The process repeats automatically at 8:00 AM

Complete Configuration

Here's the full config with both the task and runner:

1import { buildConfig } from 'payload'
2
3export default buildConfig({
// ... other config
jobs: {
  tasks: [
    {
      slug: 'generateDailyReport',
      schedule: [
        {
          cron: '0 8 * * *',
          queue: 'reports',
        },
      ],
      handler: async ({ req }) => {
        // Report generation logic
        const report = await generateReport()
        return { output: { reportId: report.id } }
      },
    },
  ],
  autoRun: [
    {
      cron: '* * * * *',
      queue: 'reports',
      limit: 10,
    },
  ],
},
30})

When to Use Each Approach

Approach	When to Use	Example
Manual Queuing	Jobs triggered by user actions or data changes	Welcome emails, payment processing, notifications
Scheduled Jobs	Jobs that run automatically at regular intervals	Daily reports, weekly cleanups, nightly syncs
Scheduled with Future	One-time job in the future	Publish post at 3pm tomorrow, trial expiry reminders

For scheduled jobs with waitUntil:

1// Queue a one-time job for the future
2await payload.jobs.queue({
3  task: 'publishPost',
4  input: { postId: '123' },
5  waitUntil: new Date('2024-12-25T15:00:00Z'), // Runs once at this time
6})

This is different from the schedule property, which repeats automatically.

See Job Schedules for more details on scheduling options and advanced patterns.

Was this page helpful?

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.