Scheduling a one-off function

Inngest provides a way to delay a function run to a specific time in the future. This is useful when:

You want to schedule work in the future based on user input.
You want to slightly delay execution of a non-urgent function for a few seconds or minutes.

This page provides a quick example of how to delay a function run to a specific time in the future using the event payload's ts field.

Quick Snippet

Here is a basic function that sends a reminder to a user at a given email.

const sendReminder = inngest.createFunction(
  { id: "send-reminder" },
  { event: "notifications/reminder.scheduled" },
  async ({ event, step }) => {
    const { user, message } = event.data;

    const { id } = await emailApi.send({
      to: user.email,
      subject: "Reminder for your upcoming event",
      body: message,
    });

    return { id }
  }
);

Triggering the function with a timestamp

To trigger this function, you will send an event "notifications/reminder.scheduled" using inngest.send() with the necessary data. The ts field in the event payload should be set to the Unix timestamp of the time you want the function to run. For example, to schedule a reminder for 5 minutes in the future:

await inngest.send({
  name: "notifications/reminder.scheduled",
  data: {
    user: { email: "johnny.utah@fbi.gov" }
    message: "Don't forget to catch the wave at 3pm",
  },
  // Include the timestamp for 5 minutes in the future:
  ts: Date.now() + 5 * 60 * 1000,
});

⚠️ Providing a timestamp in the event only applies for starting function runs. Functions waiting for a matching event will immediately resume, regardless of the timestamp.

Alternatives

Depending on your use case, you may want to consider using scheduled functions (cron jobs) for scheduling periodic work or use step.sleepUntil() to add mid-function delays for a layer time.

More context

Check the resources below to learn more about scheduling functions with Inngest.

Guide: Sending events