Edit

Share via

Office.DelayDeliveryTime interface

  • Reference
Package:
outlook

The DelayDeliveryTime object enables you to manage the delayed delivery date and time of a message.

Remarks

[ API set: Mailbox 1.13 ]

Minimum permission level: read item

Applicable Outlook mode: Compose

Methods

getAsync(options, callback)

Gets the delivery date and time of a message.
getAsync(callback)

Gets the delivery date and time of a message.
setAsync(datetime, options, callback)

Sets the delivery date and time of a message.
setAsync(datetime, callback)

Sets the delivery date and time of a message.

Method Details

getAsync(options, callback)

Gets the delivery date and time of a message.

getAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<Date | 0>) => void): void;

Parameters

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<Date | 0>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. The delivery date and time of a message is returned in the asyncResult.value property. If a delivery date hasn't been set on a message yet, 0 is returned instead.

Returns

void

Remarks

[ API set: Mailbox 1.13 ]

Minimum permission level: read item

Applicable Outlook mode: Compose

getAsync(callback)

Gets the delivery date and time of a message.

getAsync(callback?: (asyncResult: Office.AsyncResult<Date | 0>) => void): void;

Parameters

callback

(asyncResult: Office.AsyncResult<Date | 0>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. The delivery date and time of a message is returned in the asyncResult.value property. If a delivery date hasn't been set on a message yet, 0 is returned instead.

Returns

void

Remarks

[ API set: Mailbox 1.13 ]

Minimum permission level: read item

Applicable Outlook mode: Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/delay-message-delivery.yaml

// This snippet 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()}`);
  }
});

setAsync(datetime, options, callback)

Sets the delivery date and time of a message.

setAsync(datetime: Date, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

datetime

Date

The future date and time when the message should be sent.

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. Any errors encountered will be provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.13 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Important:

  • When item.delayDeliveryTime.setAsync is used to schedule the delivery of a message, the delay is processed on the server. This allows the message to be sent even if the Outlook client isn't running. In classic Outlook on Windows, 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 only be able to review the message from the Sent Items folder. In Outlook on the web, on Mac, and in new Outlook on Windows, the message appears in the Drafts folder until the scheduled delivery time. While it's in the Drafts folder, you'll be able to edit the message before it's sent. To learn more, see Manage the delivery date and time of a message.

  • The setAsync method isn't supported on a message that's currently loaded using the loadItemByIdAsync method. For more information, see Activate your Outlook add-in on multiple messages.

Errors:

  • InvalidFormatError - The format of the specified data object is not valid.

setAsync(datetime, callback)

Sets the delivery date and time of a message.

setAsync(datetime: Date, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

datetime

Date

The future date and time when the message should be sent.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. Any errors encountered will be provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.13 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Important:

  • When item.delayDeliveryTime.setAsync is used to schedule the delivery of a message, the delay is processed on the server. This allows the message to be sent even if the Outlook client isn't running. In classic Outlook on Windows, 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 only be able to review the message from the Sent Items folder. In Outlook on the web, on Mac, and in new Outlook on Windows, the message appears in the Drafts folder until the scheduled delivery time. While it's in the Drafts folder, you'll be able to edit the message before it's sent. To learn more, see Manage the delivery date and time of a message.

  • The setAsync method isn't supported on a message that's currently loaded using the loadItemByIdAsync method. For more information, see Activate your Outlook add-in on multiple messages.

Errors:

  • InvalidFormatError - The format of the specified data object is not valid.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/delay-message-delivery.yaml

function setDeliveryDate(minutes) {
  // This snippet sets the delivery date and time of a message.
  const currentTime = new Date().getTime();
  const milliseconds = totalDelay * 60000;
  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;
    }

    if (minutes === 1440) {
      console.log(`Delayed delivery by an additional one day.`);
    } else {
      console.log(`Delayed delivery by an additional ${minutes} minutes.`);
    }
  });
}