Edit

Manage the delivery date and time of a message

  • Article

The Outlook client gives you the option to delay the delivery of a message, but requires you to keep Outlook and your device running to send it at the specified time. With the Office JavaScript API, you can now implement an Outlook add-in that sends scheduled messages even with your Outlook client closed or with your device turned off. This capability provides your users with the convenience to schedule email marketing campaigns or time a message to be delivered during a colleague or customer's business hours.

Note

Support for this feature was introduced in requirement set 1.13. See clients and platforms that support this requirement set.

Configure the manifest

To schedule the delivery of a message, your add-in must be able to activate in message compose mode. This is defined through the MessageComposeCommandSurface extension point in an XML manifest or the mailCompose "contexts" property in a Unified manifest for Microsoft 365 (preview).

For further guidance on how to configure an Outlook add-in manifest, see Office add-in manifests.

Access the delivery property of a message

The item.delayDeliveryTime property returns a DelayDeliveryTime object that provides you with methods to get or set the delivery date and time of a message.

Get the delivery date and time of a message

To get the delivery date and time of a message in compose mode, call item.delayDeliveryTime.getAsync as shown in the following example. If a delivery date hasn't been set on a message yet, the call returns 0. Otherwise, it returns a JavaScript Date object.

// Gets the delivery date and time of a message.
Office.context.mailbox.item.delayDeliveryTime.getAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  const deliveryDate = asyncResult.value;
  if (deliveryDate === 0) {
    console.log("Your message will be delivered immediately when you select Send.");
  } else {
    const date = new Date(deliveryDate);
    console.log(`Message delivery date and time: ${date.toString()}`);
  }
});

Set the delivery date and time of a message

To delay the delivery of a message, pass a JavaScript Date object as a parameter to item.delayDeliveryTime.setAsync method, as shown in the following example.

// Delays the delivery time by five minutes from the current time.
const currentTime = new Date().getTime();
const milliseconds = 5 * 60 * 1000;
const timeDelay = new Date(currentTime + milliseconds);
Office.context.mailbox.item.delayDeliveryTime.setAsync(timeDelay, (asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  console.log("Message delivery has been scheduled.");
});

Feature behavior and limitations

When you schedule the delivery of a message using the item.delayDeliveryTime.setAsync method, the delay is processed on the server. This allows the message to be sent even if the Outlook client isn’t running. However, because of this, the message doesn't appear in the Outbox folder, so you won't be able to edit the message or cancel its delivery after selecting Send. You'll be able to review the message from the Sent Items folder once the message is sent.

This behavior differs from a message scheduled using the native Delay Delivery option in the Outlook client, which processes the delay client-side. A message scheduled using this option appears in the Outbox folder and is only delivered if the Outlook client from which it was sent is running at the specified delivery time.

Try sample snippets in Script Lab

Get the Script Lab for Outlook add-in and try out the "Get and set message delivery (Message Compose)" sample snippet. To learn more about Script Lab, see Explore Office JavaScript API using Script Lab.

The message delivery sample snippet in Script Lab.

Note

Starting in Version 115 of Chromium-based browsers, such as Chrome and Edge, storage partitioning is being tested to prevent specific side-channel cross-site tracking (see also Microsoft Edge browser policies). This change is preventing Script Lab snippets from running in Outlook on the web. To work around this, go to chrome://flags or edge://flags in your browser, then set the Third-party Storage Partitioning (#third-party-storage-partitioning) flag to Disabled.

See also