Office.AppointmentCompose interface

Gets an object that provides methods for manipulating the body of an item.

body: Body;

Property Value

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// This example gets the body of the item as plain text.
Office.context.mailbox.item.body.getAsync(
    "text",
    { asyncContext: "This is passed to the callback" },
    function callback(result) {
        // Do something with the result.
    });

// The following is an example of an object that is passed as the result parameter to the callback function.
{
    "value": "TEXT of whole body (including threads below)",
    "status": "succeeded",
    "asyncContext": "This is passed to the callback"
}

Gets an object that provides methods for managing the item's categories.

categories: Categories;

Property Value

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-categories.yaml

Office.context.mailbox.item.categories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Categories assigned to this item:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories assigned to this item.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

// Note: In order for you to successfully add a category,
// it must be in the mailbox categories master list.

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const masterCategories = asyncResult.value;
    if (masterCategories && masterCategories.length > 0) {
      // Grab the first category from the master list.
      const categoryToAdd = [masterCategories[0].displayName];
      Office.context.mailbox.item.categories.addAsync(categoryToAdd, function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
          console.log(`Successfully assigned category '${categoryToAdd}' to item.`);
        } else {
          console.log("categories.addAsync call failed with error: " + asyncResult.error.message);
        }
      });
    } else {
      console.log("There are no categories in the master list on this mailbox. You can add categories using Office.context.mailbox.masterCategories.addAsync.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.categories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      // Grab the first category assigned to this item.
      const categoryToRemove = [categories[0].displayName];
      Office.context.mailbox.item.categories.removeAsync(categoryToRemove, function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
          console.log(`Successfully unassigned category '${categoryToRemove}' from this item.`);
        } else {
          console.log("categories.removeAsync call failed with error: " + asyncResult.error.message);
        }
      });
    } else {
      console.log("There are no categories assigned to this item.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

Gets or sets the date and time that the appointment is to end.

The end property is a Time object expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client's local date and time.

When you use the Time.setAsync method to set the end time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server.

Important: In the Windows client, you can't use this property to update the end of a recurrence.

end: Time;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// The following example sets the end time of an appointment in compose mode by
// using the `setAsync` method of the `Time` object.
const endTime = new Date("3/14/2015");
const options = {
    // Pass information that can be used in the callback.
    asyncContext: {verb: "Set"}
};
Office.context.mailbox.item.end.setAsync(endTime, options, function(result) {
    if (result.error) {
        console.debug(result.error);
    } else {
        // Access the asyncContext that was passed to the setAsync method.
        console.debug("End Time " + result.asyncContext.verb);
    }
});

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-set-end-appointment-organizer.yaml

Office.context.mailbox.item.end.getAsync((result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Appointment ends: ${result.value}`);
});

...

Office.context.mailbox.item.start.getAsync((result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Get start date failed with message ${result.error.message}`);
    return;
  }

  const end = result.value; // Set end to current start date and time.
  end.setDate(end.getDate() + 1); // Set end as 1 day later than start date.
  Office.context.mailbox.item.end.setAsync(end, (result) => {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
      console.error(`Set end date failed with message ${result.error.message}`);
      return;
    }
    console.log(`Successfully set end date and time to ${end}`);
  });
});

Gets or sets the locations of the appointment. The enhancedLocation property returns an EnhancedLocation object that provides methods to get, remove, or add locations on an item.

enhancedLocation: EnhancedLocation;

Property Value

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-add-remove-enhancedlocation-appointment.yaml

Office.context.mailbox.item.enhancedLocation.getAsync((result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Failed to get locations. Error message: ${result.error.message}`);
    return;
  }
  const places = result.value;
  if (places && places.length > 0) {
    result.value.forEach(function(place) {
      console.log(`Location: ${place.displayName} (type: ${place.locationIdentifier.type})`);
      if (place.locationIdentifier.type === Office.MailboxEnums.LocationType.Room) {
        console.log("Email address: " + place.emailAddress);
      }
    });
  } else {
    console.log("There are no locations.");
  }
});

...

const locations = [
  {
    id: "Contoso",
    type: Office.MailboxEnums.LocationType.Custom
  },
  {
    id: "[email protected]",
    type: Office.MailboxEnums.LocationType.Room
  }
];
Office.context.mailbox.item.enhancedLocation.addAsync(locations, (result) => {
  if (result.status === Office.AsyncResultStatus.Succeeded) {
    console.log(`Successfully added locations ${JSON.stringify(locations)}`);
  } else {
    console.error(`Failed to add locations. Error message: ${result.error.message}`);
  }
});

...

const locations = [
  {
    id: "Contoso",
    type: Office.MailboxEnums.LocationType.Custom
  },
  {
    id: "[email protected]",
    type: Office.MailboxEnums.LocationType.Room
  }
];
Office.context.mailbox.item.enhancedLocation.removeAsync(locations, (result) => {
  if (result.status === Office.AsyncResultStatus.Succeeded) {
    console.log(`Successfully removed locations ${JSON.stringify(locations)}`);
  } else {
    console.error(`Failed to remove locations. Error message: ${result.error.message}`);
  }
});

Gets the type of item that an instance represents.

The itemType property returns one of the ItemType enumeration values, indicating whether the item object instance is a message or an appointment.

itemType: MailboxEnums.ItemType | string;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

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

const itemType = Office.context.mailbox.item.itemType;
switch (itemType) {
    case Office.MailboxEnums.ItemType.Appointment:
        console.log(`Current item is an ${itemType}.`);
        break;
    case Office.MailboxEnums.ItemType.Message:
        console.log(`Current item is a ${itemType}. A message could be an email, meeting request, meeting response, or meeting cancellation.`);
        break;
}

Gets or sets the location of an appointment. The location property returns a Location object that provides methods that are used to get and set the location of the appointment.

location: Location;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

const userContext = { value : 1 };
Office.context.mailbox.item.location.getAsync( { context: userContext}, callback);

function callback(asyncResult) {
    const context = asyncResult.context;
    const location = asyncResult.value;
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-set-location-appointment-organizer.yaml

Office.context.mailbox.item.location.getAsync((result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Appointment location: ${result.value}`);
});

...

const location = "my office";
Office.context.mailbox.item.location.setAsync(location, (result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Successfully set location to ${location}`);
});

Gets the notification messages for an item.

notificationMessages: NotificationMessages;

Property Value

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml

// Adds a progress indicator to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.ProgressIndicator,
    message: "Progress indicator with id = " + id
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds an informational notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Non-persistent informational notification message with id = " + id,
    icon: "icon1",
    persistent: false
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds a persistent information notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Persistent informational notification message with id = " + id,
    icon: "icon1",
    persistent: true
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Gets all the notification messages and their keys for the current mail item.
Office.context.mailbox.item.notificationMessages.getAllAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  console.log(asyncResult.value);
});

...

// Replaces a notification message of a given key with another message.
const id = $("#notificationId").val().toString();
Office.context.mailbox.item.notificationMessages.replaceAsync(
  id,
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Notification message with id = " + id + " has been replaced with an informational message.",
    icon: "icon2",
    persistent: false
  },
  handleResult);

...

// Removes a notification message from the current mail item.
const id = $("#notificationId").val().toString();
Office.context.mailbox.item.notificationMessages.removeAsync(id, handleResult);

Provides access to the optional attendees of an event. The type of object and level of access depend on the mode of the current item.

The optionalAttendees property returns a Recipients object that provides methods to get or update the optional attendees for a meeting. However, depending on the client/platform (i.e., Windows, Mac, etc.), limits may apply on how many recipients you can get or update. See the Recipients object for more details.

optionalAttendees: Recipients;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

Office.context.mailbox.item.optionalAttendees.setAsync( ['[email protected]', '[email protected]'] );
Office.context.mailbox.item.optionalAttendees.addAsync( ['[email protected]'] );
Office.context.mailbox.item.optionalAttendees.getAsync(callback);

function callback(asyncResult) {
    const arrayOfOptionalAttendeesRecipients = asyncResult.value;
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-set-optional-attendees-appointment-organizer.yaml

Office.context.mailbox.item.optionalAttendees.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const apptOptionalAttendees = asyncResult.value;
    for (let i = 0; i < apptOptionalAttendees.length; i++) {
      console.log(
        "Optional attendees: " +
          apptOptionalAttendees[i].displayName +
          " (" +
          apptOptionalAttendees[i].emailAddress +
          ") - response: " +
          apptOptionalAttendees[i].appointmentResponse
      );
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = $("#emailOptional")
  .val()
  .toString();
const emailArray = [email];
Office.context.mailbox.item.optionalAttendees.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting optional attendees field.");
  } else {
    console.error(asyncResult.error);
  }
});

Gets the organizer for the specified meeting.

The organizer property returns an Organizer object that provides a method to get the organizer value.

organizer: Organizer;

Property Value

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-organizer-appointment-organizer.yaml

Office.context.mailbox.item.organizer.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const apptOrganizer = asyncResult.value;
    console.log("Organizer: " + apptOrganizer.displayName + " (" + apptOrganizer.emailAddress + ")");
  } else {
    console.error(asyncResult.error);
  }
});

Gets or sets the recurrence pattern of an appointment.

The recurrence property returns a recurrence object for recurring appointments or meetings requests if an item is a series or an instance in a series. null is returned for single appointments and meeting requests of single appointments.

Note: Meeting requests have an itemClass value of IPM.Schedule.Meeting.Request.

Note: If the recurrence object is null, this indicates that the object is a single appointment or a meeting request of a single appointment and NOT a part of a series.

recurrence: Recurrence;

Property Value

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/50-recurrence/get-set-recurrence-appointment-organizer.yaml

Office.context.mailbox.item.recurrence.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const recurrence = asyncResult.value;
    if (recurrence === null) {
      console.log("This is a single appointment.");
    } else {
      console.log(`Recurrence pattern: ${JSON.stringify(recurrence)}`);
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

// Important: Can only set the recurrence pattern of an appointment series.

const currentDate = new Date();
let seriesTimeObject: Office.SeriesTime;
// Set series start date to tomorrow.
seriesTimeObject.setStartDate(currentDate.getFullYear(), currentDate.getMonth(), currentDate.getDay() + 1);
// Set series end date to one year from now.
seriesTimeObject.setEndDate(currentDate.getFullYear() + 1, currentDate.getMonth() + 1, currentDate.getDay());
// Set start time to 1:30 PM.
seriesTimeObject.setStartTime(13, 30);
// Set duration to 30 minutes.
seriesTimeObject.setDuration(30);

const pattern: Office.Recurrence = {
  seriesTime: seriesTimeObject,
  recurrenceType: Office.MailboxEnums.RecurrenceType.Yearly,
  recurrenceProperties: {
    interval: 1,
    dayOfWeek: Office.MailboxEnums.Days.Tue,
    weekNumber: Office.MailboxEnums.WeekNumber.Second,
    month: Office.MailboxEnums.Month.Sep
  },
  recurrenceTimeZone: { name: Office.MailboxEnums.RecurrenceTimeZone.PacificStandardTime }
};

Office.context.mailbox.item.recurrence.setAsync(pattern, (asyncResult) => {
  if (asyncResult.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Failed to set recurrence. Error: ${asyncResult.error.message}`);
    return;
  }
  console.log(`Succeeded in setting recurrence pattern ${JSON.stringify(pattern)}`);
});

Provides access to the required attendees of an event. The type of object and level of access depend on the mode of the current item.

The requiredAttendees property returns a Recipients object that provides methods to get or update the required attendees for a meeting. However, depending on the client/platform (i.e., Windows, Mac, etc.), limits may apply on how many recipients you can get or update. See the Recipients object for more details.

requiredAttendees: Recipients;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

Office.context.mailbox.item.requiredAttendees.setAsync( ['[email protected]', '[email protected]'] );
Office.context.mailbox.item.requiredAttendees.addAsync( ['[email protected]'] );
Office.context.mailbox.item.requiredAttendees.getAsync(callback);

function callback(asyncResult) {
    const arrayOfRequiredAttendeesRecipients = asyncResult.value;
    console.log(JSON.stringify(arrayOfRequiredAttendeesRecipients));
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-set-required-attendees-appointment-organizer.yaml

Office.context.mailbox.item.requiredAttendees.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const apptRequiredAttendees = asyncResult.value;
    for (let i = 0; i < apptRequiredAttendees.length; i++) {
      console.log(
        "Required attendees: " +
          apptRequiredAttendees[i].displayName +
          " (" +
          apptRequiredAttendees[i].emailAddress +
          ") - response: " +
          apptRequiredAttendees[i].appointmentResponse
      );
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = $("#emailRequired")
  .val()
  .toString();
const emailArray = [email];
Office.context.mailbox.item.requiredAttendees.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting required attendees field.");
  } else {
    console.error(asyncResult.error);
  }
});

Gets the ID of the series that an instance belongs to.

In Outlook on the web, on Windows (new and classic), and on Mac, the seriesId property returns the Exchange Web Services (EWS) ID of the parent (series) item that this item belongs to. However, in Outlook on Android and on iOS, seriesId returns the REST ID of the parent item.

Note: The identifier returned by the seriesId property is the same as the Exchange Web Services item identifier. The seriesId property isn't identical to the Outlook IDs used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in.

The seriesId property returns null for items that don't have parent items such as single appointments, series items, or meeting requests and returns undefined for any other items that aren't meeting requests.

seriesId: string;

Property Value

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/50-recurrence/get-series-id.yaml

const seriesId = Office.context.mailbox.item.seriesId;

if (seriesId === undefined) {
  console.log("This is a message that's not a meeting request.");
} else if (seriesId === null) {
  console.log("This is a single appointment, a parent series, or a meeting request for a series or single meeting.");
} else {
  console.log("This is an instance belonging to series with ID " + seriesId);
}

Manages the SessionData of an item in Compose mode.

Important: The entire SessionData object is limited to 50,000 characters per add-in.

sessionData: SessionData;

Property Value

Remarks

[ API set: Mailbox 1.11 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

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

Office.context.mailbox.item.sessionData.getAllAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("The sessionData is " + JSON.stringify(asyncResult.value));
  } else {
    console.log("Failed to get all sessionData. Error: " + JSON.stringify(asyncResult.error));
  }
});

Gets or sets the date and time that the appointment is to begin.

The start property is a Time object expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client's local date and time.

When you use the Time.setAsync method to set the start time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server.

Important: In the Windows client, you can't use this property to update the start of a recurrence.

start: Time;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-set-start-appointment-organizer.yaml

Office.context.mailbox.item.start.getAsync((result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Appointment starts: ${result.value}`);
});

...

const start = new Date(); // Represents current date and time.
start.setDate(start.getDate() + 2); // Add 2 days to current date.
Office.context.mailbox.item.start.setAsync(start, (result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Successfully set start date and time to ${start}`);
});

Gets or sets the description that appears in the subject field of an item.

The subject property gets or sets the entire subject of the item, as sent by the email server.

The subject property returns a Subject object that provides methods to get and set the subject.

subject: Subject;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-set-subject-compose.yaml

Office.context.mailbox.item.subject.getAsync((result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Subject: ${result.value}`);
});

...

let subject = "Hello World!";
Office.context.mailbox.item.subject.setAsync(subject, (result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Successfully set subject to ${subject}`);
});

Adds a file to a message or appointment as an attachment.

The addFileAttachmentAsync method uploads the file at the specified URI and attaches it to the item in the compose form.

addFileAttachmentAsync(uri: string, attachmentName: string, options: Office.AsyncContextOptions & { isInline: boolean }, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 for Outlook on Windows (classic) and on Mac, Mailbox 1.8 for Outlook on the web and new Outlook on Windows ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Important:

• This method isn't supported in Outlook on iOS or Android. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

• In recent builds of classic Outlook on Windows, a bug was introduced that incorrectly appends an Authorization: Bearer header to this action (whether using this API or the Outlook UI). To work around this issue, use the addFileAttachmentFromBase64 API introduced with requirement set 1.8.

• The URI of the file to be attached must support caching in production. The server hosting the image shouldn't return a Cache-Control header that specifies no-cache, no-store, or similar options in the HTTP response. However, when you're developing the add-in and making changes to files, caching can prevent you from seeing your changes. We recommend using Cache-Control headers during development.

• You can use the same URI with the removeAttachmentAsync method to remove the attachment in the same session.

Errors:

• AttachmentSizeExceeded: The attachment is larger than allowed.

• FileTypeNotSupported: The attachment has an extension that is not allowed.

• NumberOfAttachmentsExceeded: The message or appointment has too many attachments.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/attachments-compose.yaml

const attachmentUrl = $("#attachmentUrl")
  .val()
  .toString();
Office.context.mailbox.item.addFileAttachmentAsync(
  attachmentUrl,
  getFileName(attachmentUrl),
  { isInline: false },
  (result) => {
    console.log(result);
  }
);

Adds a file to a message or appointment as an attachment.

The addFileAttachmentAsync method uploads the file at the specified URI and attaches it to the item in the compose form.

addFileAttachmentAsync(uri: string, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 for Outlook on Windows (classic) and on Mac, Mailbox 1.8 for Outlook on the web and new Outlook on Windows ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Important:

• This method isn't supported in Outlook on iOS or Android. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

• In recent builds of classic Outlook on Windows, a bug was introduced that incorrectly appends an Authorization: Bearer header to this action (whether using this API or the Outlook UI). To work around this issue, use the addFileAttachmentFromBase64 API introduced with requirement set 1.8.

• The URI of the file to be attached must support caching in production. The server hosting the image shouldn't return a Cache-Control header that specifies no-cache, no-store, or similar options in the HTTP response. However, when you're developing the add-in and making changes to files, caching can prevent you from seeing your changes. We recommend using Cache-Control headers during development.

• You can use the same URI with the removeAttachmentAsync method to remove the attachment in the same session.

Errors:

• AttachmentSizeExceeded: The attachment is larger than allowed.

• FileTypeNotSupported: The attachment has an extension that is not allowed.

• NumberOfAttachmentsExceeded: The message or appointment has too many attachments.

Adds a file to a message or appointment as an attachment.

The addFileAttachmentFromBase64Async method uploads the file from the Base64 encoding and attaches it to the item in the compose form. This method returns the attachment identifier in the asyncResult.value object.

You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session.

Note: If you're using a data URL API (e.g., readAsDataURL), you need to strip out the data URL prefix then send the rest of the string to this API. For example, if the full string is represented by data:image/svg+xml;base64,<rest of Base64 string>, remove data:image/svg+xml;base64,.

addFileAttachmentFromBase64Async(base64File: string, attachmentName: string, options: Office.AsyncContextOptions &  { isInline: boolean }, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Errors:

• AttachmentSizeExceeded: The attachment is larger than allowed.

• FileTypeNotSupported: The attachment has an extension that isn't allowed.

• NumberOfAttachmentsExceeded: The message or appointment has too many attachments.

Note: If you're adding an inline Base64 image to the body of a message or appointment being composed, you must first get the current item body using the Office.context.mailbox.item.body.getAsync method before inserting the image using addFileAttachmentFromBase64Async. Otherwise, the image won't render in the body once it's inserted. For further guidance, see Attach a file.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/attachments-compose.yaml

const base64String =
  "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAsSAAALEgHS3X78AAACRUlEQVRYw82XzXHbMBCFP2F8tzsQc8Ixyh0zoiuIXIGdCsxUYKqC0B04FdiuwMoM7mGOOIXqQGoAymXhgSX+itJM9kIRFLAP+3YXD5Pdbscx5oxaAIW8Ztr6l2PWmQwF4IyaieP53qdfAqQ8CwBn1JU4vpWhrbxXQA5MZfynANmcDIAzKgcy4FKGXsVJFf3nLgKyBQptfT4KQMRz2N0fcbxqmRMDWXflx0VPnrdArq0vekQ1Dv0UeHZGNebHhwjU8AzwKM43RyZnbAf58Q6ghudeWd0Aus0+5EcMIIRi3beua0D3Nm39BEAx3i7HTK4DEBJn5YxKOnaRA5+ErpMBWMpzDvx1RuXCcxOISlufAjfC7zgAsqsvUvMAD0ApPaEtGi9AIlUzKgJo60tt/SyKRkzLrAXERluf7W1gOICWaMyB386oooOWsIHvXbSoHuUSFovtHqicUVnH3EJoeT0aQEf5/XBGlc6otIOWBXAtPeZkAIJ9Bt6cUU9tZautX2nrk3MACHYr1ZKProKRtDw4o8pzAPjWo+NtpXTTvoteDDg8noDAcwbcRedAkGdFXyk2GEDcegVAFp2gyVDHjRQ4o6q2smoqtR5Hd+qMqtoALCWUUymr1m43QMZfOaMK4C0SrMsDANJ2E5FNcbdbjHC+ENl+H0myJFbLtaq4Rt8dyPBYRQV1E40nMv9rl7xrOw3DGb+Whcqu3i/OM6CUOWvgRlufNmnLYy4m77uJI7AXtdNcTDrU71LEyv7v01/N/ovL6bmu5/8A1tNWZldH0W4AAAAASUVORK5CYII=";
Office.context.mailbox.item.addFileAttachmentFromBase64Async(
  base64String,
  "logo.png",
  { isInline: false },
  (result) => {
    console.log(result);
  }
);

...

// Set the signature for the current item with inline image.
const modIcon1Base64 = "iVBORw0KGgoAAAANSUhEUgAAABwAAAAcCAYAAAByDd+UAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAA2ZpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYxIDY0LjE0MDk0OSwgMjAxMC8xMi8wNy0xMDo1NzowMSAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wTU09Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9tbS8iIHhtbG5zOnN0UmVmPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvc1R5cGUvUmVzb3VyY2VSZWYjIiB4bWxuczp4bXA9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC8iIHhtcE1NOk9yaWdpbmFsRG9jdW1lbnRJRD0ieG1wLmRpZDpDRDMxMDg1MjBCNDZFMTExODE2MkM1RUI2M0M4MDYxRCIgeG1wTU06RG9jdW1lbnRJRD0ieG1wLmRpZDpFMTUxQjgyRjQ2MEQxMUUxODlFMkQwNTYzQ0YwMTUxMiIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDpFMTUxQjgyRTQ2MEQxMUUxODlFMkQwNTYzQ0YwMTUxMiIgeG1wOkNyZWF0b3JUb29sPSJBZG9iZSBQaG90b3Nob3AgQ1M1LjEgV2luZG93cyI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAuaWlkOkQxMzEwODUyMEI0NkUxMTE4MTYyQzVFQjYzQzgwNjFEIiBzdFJlZjpkb2N1bWVudElEPSJ4bXAuZGlkOkNEMzEwODUyMEI0NkUxMTE4MTYyQzVFQjYzQzgwNjFEIi8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4bXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+uC/WfAAAAehJREFUeNpilCzfwEAEkAbiECA2A2J1IOaHin8E4ptAfBaIVwLxU0IGMRKw0B6IW4DYhoE4cASIK6E0VsCEQ1wUiNcB8QESLGOAqj0MxBuhZhBloS4QnwHiQAbygR/UDF1CFupCXSjHQDmQg5qli8tCUBBsQUoQ1AD8UDNFsVk4n0o+w+bT+egWglKjNymmeGhLkqLcG2oHAwtUoIuQDj5OVgZPLUmwRe5aEmAxqYqNpFgKssOcCeplM0KqdST5GfpDDRm0JfkYrj3/SE7QguyQY4ImYYLgCtAS10kHGMw6dzNsv/qC7OwCClJXYlR++v6b4er3j5QmIFcmaNlIL6AOslCIjhYKMTHQGTBBqxh6gXcgC6/R0cKbIAv30dHCfaAKGJTxHxJSqS3Fz9DkowNmywpyMcgA8fF7b8D8VWcfM6w8+4gYC+VB+RCk8hSh0gaUD4/dewvlvUWRe/z+GzGWgex4BGtiOAHxXhoHpzMoSGHZAhSPW2lo2VZYWkHOh4nEtLrIAE+hZmNUwK+B2BOIv1PRsu9QM1/jatNcBtVZ0IREKXgENesyoVYbzNIdFFi2A5tl+NqlL6BB4QBNzsSCU1A9nlAzMAALAQMOQl0qB23qWwKxIlIrDBQ394H4OBCvISYqAAIMACVibHDqsO7zAAAAAElFTkSuQmCC";
Office.context.mailbox.item.addFileAttachmentFromBase64Async(
  modIcon1Base64,
  "myImage.png",
  { isInline: true },
  function(result) {
    if (result.status == Office.AsyncResultStatus.Succeeded) {
      const signature = $("#signature").val() + "<img src='cid:myImage.png'>";
      console.log(`Setting signature to "${signature}".`);
      Office.context.mailbox.item.body.setSignatureAsync(
        signature,
        { coercionType: "html" },
        function(asyncResult) {
          console.log(`setSignatureAsync: ${asyncResult.status}`);
        }
      );
    } else {
      console.error(`addFileAttachmentFromBase64Async: ${result.error}`);
    }
  }
);

Adds a file to a message or appointment as an attachment.

The addFileAttachmentFromBase64Async method uploads the file from the Base64 encoding and attaches it to the item in the compose form. This method returns the attachment identifier in the asyncResult.value object.

You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session.

Note: If you're using a data URL API (e.g., readAsDataURL), you need to strip out the data URL prefix then send the rest of the string to this API. For example, if the full string is represented by data:image/svg+xml;base64,<rest of Base64 string>, remove data:image/svg+xml;base64,.

addFileAttachmentFromBase64Async(base64File: string, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Errors:

• AttachmentSizeExceeded: The attachment is larger than allowed.

• FileTypeNotSupported: The attachment has an extension that isn't allowed.

• NumberOfAttachmentsExceeded: The message or appointment has too many attachments.

Note: If you're adding an inline Base64 image to the body of a message or appointment being composed, you must first get the current item body using the Office.context.mailbox.item.body.getAsync method before inserting the image using addFileAttachmentFromBase64Async. Otherwise, the image won't render in the body once it's inserted. For further guidance, see Attach a file.

Adds an event handler for a supported event. Note: Events are only available with task pane implementation.

For supported events, refer to the Item object model events section.

addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

function myHandlerFunction(eventarg) {
    if (eventarg.attachmentStatus === Office.MailboxEnums.AttachmentStatus.Added) {
        const attachment = eventarg.attachmentDetails;
        console.log("Event Fired and Attachment Added!");
        getAttachmentContentAsync(attachment.id, options, callback);
    }
}

Office.context.mailbox.item.addHandlerAsync(Office.EventType.AttachmentsChanged, myHandlerFunction, myCallback);

Adds an event handler for a supported event. Note: Events are only available with task pane implementation.

For supported events, refer to the Item object model events section.

addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Adds an Exchange item, such as a message, as an attachment to the message or appointment.

The addItemAttachmentAsync method attaches the item with the specified Exchange identifier to the item in the compose form. If you specify a callback function, the method is called with one parameter, asyncResult, which contains either the attachment identifier or a code that indicates any error that occurred while attaching the item. You can use the options parameter to pass state information to the callback function, if needed.

You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session.

If your Office Add-in is running in Outlook on the web and new Outlook on Windows, the addItemAttachmentAsync method can attach items to items other than the item that you're editing. However, this isn't supported and isn't recommended.

addItemAttachmentAsync(itemId: any, attachmentName: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Errors:

• NumberOfAttachmentsExceeded: The message or appointment has too many attachments.

Examples

// The following example adds an existing Outlook item as an attachment
// with the name "My Attachment".
function addAttachment() {
    // EWS ID of item to attach (shortened for readability).
    const itemId = "AAMkADI1...AAA=";

    // The values in asyncContext can be accessed in the callback.
    const options = { asyncContext: { var1: 1, var2: 2 } };

    Office.context.mailbox.item.addItemAttachmentAsync(itemId, "My Attachment", options, (result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.error("Failed to add attachment: " + result.error.message);
            return;
        }

        console.log("Attachment added successfully.");
        console.log("var1: " + result.asyncContext.var1);
        console.log("var2: " + result.asyncContext.var2);
    });
}

Adds an Exchange item, such as a message, as an attachment to the message or appointment.

The addItemAttachmentAsync method attaches the item with the specified Exchange identifier to the item in the compose form. If you specify a callback function, the method is called with one parameter, asyncResult, which contains either the attachment identifier or a code that indicates any error that occurred while attaching the item. You can use the options parameter to pass state information to the callback function, if needed.

You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session.

If your Office Add-in is running in Outlook on the web and new Outlook on Windows, the addItemAttachmentAsync method can attach items to items other than the item that you're editing. However, this isn't supported and isn't recommended.

addItemAttachmentAsync(itemId: any, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Errors:

• NumberOfAttachmentsExceeded: The message or appointment has too many attachments.

Closes the current item that is being composed.

The behavior of the close method depends on the current state of the item being composed. If the item has unsaved changes, the client prompts the user to save, discard, or close the action.

In Outlook on Windows (classic) and on Mac, the close method has no effect on a reply in the Reading Pane.

close(): void;

Returns

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: restricted

Applicable Outlook mode: Appointment Organizer

Important: In Outlook on the web and new Outlook on Windows, if the item is an appointment and it has previously been saved using saveAsync, the user is prompted to save, discard, or cancel even if no changes have occurred since the item was last saved.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/25-item-save-and-close/close.yaml

Office.context.mailbox.item.close();

Disables the Outlook client signature.

In Outlook on Windows (classic) and on Mac, this API sets the signature under the "New Message" and "Replies/Forwards" sections for the sending account to "(none)", effectively disabling the signature. In Outlook on the web and new Outlook on Windows, the API disables the signature option for new mails, replies, and forwards. If the signature is selected, this API call disables it.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.10 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/work-with-client-signatures.yaml

// Disable the client signature.
Office.context.mailbox.item.disableClientSignatureAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("disableClientSignatureAsync succeeded");
  } else {
    console.error(asyncResult.error);
  }
});

Disables the Outlook client signature.

In Outlook on Windows (classic) and on Mac, this API sets the signature under the "New Message" and "Replies/Forwards" sections for the sending account to "(none)", effectively disabling the signature. In Outlook on the web and new Outlook on Windows, the API disables the signature option for new mails, replies, and forwards. If the signature is selected, this API call disables it.

disableClientSignatureAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.10 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Gets an attachment from a message or appointment and returns it as an AttachmentContent object.

The getAttachmentContentAsync method gets the attachment with the specified identifier from the item. As a best practice, you should get the attachment's identifier from a getAttachmentsAsync call, then in the same session, use that identifier to retrieve the attachment. In Outlook on the web, on mobile devices, and in new Outlook on Windows, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.

getAttachmentContentAsync(attachmentId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<AttachmentContent>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Errors:

• AttachmentTypeNotSupported: The attachment type isn't supported. Unsupported types include embedded images in Rich Text Format, or item attachment types other than email or calendar items (such as a contact or task item).

• InvalidAttachmentId: The attachment identifier does not exist.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/get-attachment-content.yaml

// Gets the attachments of the current message or appointment in compose mode.
const options = { asyncContext: { currentItem: item } };
// The getAttachmentsAsync call can only be used in compose mode.
item.getAttachmentsAsync(options, callback);

function callback(result) {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.log(result.error.message);
    return;
  }

  if (result.value.length <= 0) {
    console.log("Mail item has no attachments.");
    return;
  }

  for (let i = 0; i < result.value.length; i++) {
    // Log the attachment type and its contents to the console.
    result.asyncContext.currentItem.getAttachmentContentAsync(result.value[i].id, handleAttachmentsCallback);
  }
}

Gets an attachment from a message or appointment and returns it as an AttachmentContent object.

The getAttachmentContentAsync method gets the attachment with the specified identifier from the item. As a best practice, you should get the attachment's identifier from a getAttachmentsAsync call, then in the same session, use that identifier to retrieve the attachment. In Outlook on the web, on mobile devices, and in new Outlook on Windows, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.

getAttachmentContentAsync(attachmentId: string, callback?: (asyncResult: Office.AsyncResult<AttachmentContent>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Errors:

• AttachmentTypeNotSupported: The attachment type isn't supported. Unsupported types include embedded images in Rich Text Format, or item attachment types other than email or calendar items (such as a contact or task item).

• InvalidAttachmentId: The attachment identifier does not exist.

Gets the item's attachments as an array.

getAttachmentsAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<AttachmentDetailsCompose[]>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/attachments-compose.yaml

Office.context.mailbox.item.getAttachmentsAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(result.error.message);
    return;
  }

  if (result.value.length > 0) {
    for (let i = 0; i < result.value.length; i++) {
      const attachment = result.value[i];
      let attachmentType;
      switch (attachment.attachmentType) {
        case Office.MailboxEnums.AttachmentType.Cloud:
          attachmentType = "Attachment is stored in a cloud location";
          break;
        case Office.MailboxEnums.AttachmentType.File:
          attachmentType = "Attachment is a file";
          break;
        case Office.MailboxEnums.AttachmentType.Item:
          attachmentType = "Attachment is an Exchange item";
          break;
      }
      console.log(
        "ID: " +
          attachment.id +
          "\n" +
          "Type: " +
          attachmentType +
          "\n" +
          "Name: " +
          attachment.name +
          "\n" +
          "Size: " +
          attachment.size +
          "\n" +
          "isInline: " +
          attachment.isInline
      );
    }
  } else {
    console.log("No attachments on this message.");
  }
});

Gets the item's attachments as an array.

getAttachmentsAsync(callback?: (asyncResult: Office.AsyncResult<AttachmentDetailsCompose[]>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Gets initialization data passed when the add-in is activated by an actionable message.

getInitializationContextAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Get the initialization context (if present).
Office.context.mailbox.item.getInitializationContextAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
        if (asyncResult.value.length > 0) {
            // The value is a string, parse to an object.
            const context = JSON.parse(asyncResult.value);
            // Do something with context.
        } else {
            // Empty context, treat as no context.
        }
    } else {
        // Handle the error.
    }
});

Gets initialization data passed when the add-in is activated by an actionable message.

getInitializationContextAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Asynchronously gets the Exchange Web Services (EWS) item identifier of a saved item.

When invoked, this method returns the item ID via the callback function.

getItemIdAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Important:

• The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId.

• If your add-in calls getItemIdAsync (for example, to get an item ID to use with EWS or the REST API), be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server. Until the item is synced, the item ID isn't recognized and using it returns an error.

Errors:

• ItemNotSaved: The ID can't be retrieved until the item is saved.

Asynchronously gets the Exchange Web Services (EWS) item identifier of a saved item.

When invoked, this method returns the item ID via the callback function.

getItemIdAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Important:

• The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId.

• If your add-in calls getItemIdAsync (for example, to get an item ID to use with EWS or the REST API), be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server. Until the item is synced, the item ID isn't recognized and using it returns an error.

Errors:

• ItemNotSaved: The ID can't be retrieved until the item is saved.

Examples

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

Office.context.mailbox.item.getItemIdAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`getItemIdAsync failed with message: ${result.error.message}`);
        return;
    }

    console.log(result.value);
});

Asynchronously returns selected data from the subject or body of a message.

If there is no selection but the cursor is in the body or subject, the method returns an empty string for the selected data. If a field other than the body or subject is selected, the method returns the InvalidSelection error.

To access the selected data from the callback function, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject.

getSelectedDataAsync(coercionType: Office.CoercionType | string, options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<any>) => void): void;

Parameters

Returns

The selected data as a string with format determined by coercionType.

Remarks

[ API set: Mailbox 1.2 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Get selected data.
Office.context.mailbox.item.getSelectedDataAsync(Office.CoercionType.Text, { option1: "option1"}, getCallback);

function getCallback(asyncResult) {
    const text = asyncResult.value.data;
    const prop = asyncResult.value.sourceProperty;

    console.log(`Selected text in ${prop}: ${text}`);
}

Asynchronously returns selected data from the subject or body of a message.

If there is no selection but the cursor is in the body or subject, the method returns an empty string for the selected data. If a field other than the body or subject is selected, the method returns the InvalidSelection error.

To access the selected data from the callback function, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject.

getSelectedDataAsync(coercionType: Office.CoercionType | string, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

The selected data as a string with format determined by coercionType.

Remarks

[ API set: Mailbox 1.2 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/20-item-body/get-selected-data.yaml

Office.context.mailbox.item.getSelectedDataAsync(Office.CoercionType.Text, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const text = asyncResult.value.data;
    const prop = asyncResult.value.sourceProperty;
    console.log("Selected text in " + prop + ": " + text);
  } else {
    console.error(asyncResult.error);
  }
});

Gets the properties of an appointment or message in a shared folder or shared mailbox.

For more information around using this API, see Enable shared folders and shared mailbox scenarios in an Outlook add-in.

getSharedPropertiesAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SharedProperties>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 for shared folder support, Mailbox 1.13 for shared mailbox support ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Note: This method isn't supported in Outlook on iOS or on Android.

Gets the properties of an appointment or message in a shared folder or shared mailbox.

For more information around using this API, see Enable shared folders and shared mailbox scenarios in an Outlook add-in.

getSharedPropertiesAsync(callback: (asyncResult: Office.AsyncResult<SharedProperties>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 for shared folder support, Mailbox 1.13 for shared mailbox support ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Note: This method isn't supported in Outlook on iOS or on Android.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/65-delegates-and-shared-folders/get-shared-properties.yaml

Office.context.mailbox.item.getSharedPropertiesAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error("The current folder or mailbox isn't shared.");
    return;
  }
  const sharedProperties = result.value;
  console.log(`Owner: ${sharedProperties.owner}`);
  console.log(`Permissions: ${sharedProperties.delegatePermissions}`);
  console.log(`Target mailbox: ${sharedProperties.targetMailbox}`);
});

Gets if the client signature is enabled.

In Outlook on Windows (classic) and on Mac, returns true if the default signature for new messages, replies, or forwards is set to a template for the sending Outlook account. In Outlook on the web and new Outlook on Windows, returns true if the signature is enabled for compose types newMail, reply, or forward. If the settings are set to "(none)" in Outlook on Windows (classic) or on Mac or disabled in Outlook on the web or new Outlook on Windows, returns false.

isClientSignatureEnabledAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.10 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/work-with-client-signatures.yaml

// Check if the client signature is currently enabled.
Office.context.mailbox.item.isClientSignatureEnabledAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("isClientSignatureEnabledAsync succeeded with result: " + asyncResult.value);
  } else {
    console.error(asyncResult.error);
  }
});

Gets if the client signature is enabled.

In Outlook on Windows (classic) and on Mac, returns true if the default signature for new messages, replies, or forwards is set to a template for the sending Outlook account. In Outlook on the web and new Outlook on Windows, returns true if the signature is enabled for compose types newMail, reply, or forward. If the settings are set to "(none)" in Outlook on Windows (classic) or on Mac or disabled in Outlook on the web or new Outlook on Windows, returns false.

isClientSignatureEnabledAsync(callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.10 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Asynchronously loads custom properties for this add-in on the selected item.

Custom properties are stored as key-value pairs on a per-app, per-item basis. This method returns a CustomProperties object in the callback, which provides methods to access the custom properties specific to the current item and the current add-in. Custom properties aren't encrypted on the item, so this shouldn't be used as secure storage.

The custom properties are provided as a CustomProperties object in the asyncResult.value property. This object can be used to get, set, save, and remove custom properties from the mail item.

loadCustomPropertiesAsync(callback: (asyncResult: Office.AsyncResult<CustomProperties>) => void, userContext?: any): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 ]

To learn more about custom properties, see Get and set add-in metadata for an Outlook add-in.

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

Office.context.mailbox.item.loadCustomPropertiesAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(`loadCustomPropertiesAsync failed with message ${result.error.message}`);
    return;
  }

  customProps = result.value;
  console.log("Loaded the CustomProperties object.");
});

Removes an attachment from a message or appointment.

The removeAttachmentAsync method removes the attachment with the specified identifier from the item. As a best practice, you should use the attachment identifier to remove an attachment only if the same mail app has added that attachment in the same session. In Outlook on the web, on mobile devices, and in new Outlook on Windows, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.

removeAttachmentAsync(attachmentId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Important*: The removeAttachmentAsync method doesn't remove inline attachments from a mail item. To remove an inline attachment, first get the item's body, then remove any references of the attachment from its contents. Use the Office.Body APIs to get and set the body of an item.

Errors:

• InvalidAttachmentId: The attachment identifier does not exist.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/attachments-compose.yaml

Office.context.mailbox.item.removeAttachmentAsync(
  $("#attachmentId")
    .val()
    .toString(),
  (result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
      console.error(result.error.message);
      return;
    }

    console.log(`Attachment removed successfully.`);
  }
);

Removes an attachment from a message or appointment.

The removeAttachmentAsync method removes the attachment with the specified identifier from the item. As a best practice, you should use the attachment identifier to remove an attachment only if the same mail app has added that attachment in the same session. In Outlook on the web, on mobile devices, and in new Outlook on Windows, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.

removeAttachmentAsync(attachmentId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Important*: The removeAttachmentAsync method doesn't remove inline attachments from a mail item. To remove an inline attachment, first get the item's body, then remove any references of the attachment from its contents. Use the Office.Body APIs to get and set the body of an item.

Errors:

• InvalidAttachmentId: The attachment identifier does not exist.

Removes the event handlers for a supported event type. Note: Events are only available with task pane implementation.

For supported events, refer to the Item object model events section.

removeHandlerAsync(eventType: Office.EventType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Removes the event handlers for a supported event type. Note: Events are only available with task pane implementation.

For supported events, refer to the Item object model events section.

removeHandlerAsync(eventType: Office.EventType | string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Organizer

Examples

Office.context.mailbox.item.removeHandlerAsync(Office.EventType.InfobarClicked, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error("Failed to remove event handler: " + asyncResult.error.message);
        return;
    }

    console.log("Event handler removed successfully.");
});

Asynchronously saves an item.

Since appointments have no draft state, if saveAsync is called on an appointment in compose mode, the item is saved as a normal appointment on the user's calendar. For new appointments that haven't been saved before, no invitation is sent. For existing appointments, an update is sent to added or removed attendees.

saveAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Important:

• In Outlook on the web, new Outlook on Windows, or classic Outlook on Windows in online mode (non-cached mode), the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache.

• When working with HTML-formatted content, it's important to note that the Outlook client may modify the content. This means that subsequent calls to methods like Body.getAsync, Body.setAsync, and even saveAsync may not result in the same content.

• The identifier returned is the same as the Exchange Web Services (EWS) item identifier. The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId.

• If your add-in calls saveAsync to get an item ID to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the item ID will return an error.

• In Outlook on Mac, only Version 16.35 (20030802) and later supports saving a meeting. Otherwise, the saveAsync method fails when called from a meeting in compose mode. For a workaround, see Cannot save a meeting as a draft in Outlook for Mac by using Office JS API.

Errors:

• InvalidAttachmentId: The attachment identifier does not exist.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/25-item-save-and-close/save.yaml

Office.context.mailbox.item.saveAsync(function (result) {
  if (result.status === Office.AsyncResultStatus.Succeeded) {
    console.log(`saveAsync succeeded, itemId is ${result.value}`);
  }
  else {
    console.error(`saveAsync failed with message ${result.error.message}`);
  }
});

Asynchronously saves an item.

Since appointments have no draft state, if saveAsync is called on an appointment in compose mode, the item is saved as a normal appointment on the user's calendar. For new appointments that haven't been saved before, no invitation is sent. For existing appointments, an update is sent to added or removed attendees.

saveAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Important:

• In Outlook on the web, new Outlook on Windows, or classic Outlook on Windows in online mode (non-cached mode), the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache.

• When working with HTML-formatted content, it's important to note that the Outlook client may modify the content. This means that subsequent calls to methods like Body.getAsync, Body.setAsync, and even saveAsync may not result in the same content.

• The identifier returned is the same as the Exchange Web Services (EWS) item identifier. The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId.

• If your add-in calls saveAsync to get an item ID to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the item ID will return an error.

• In Outlook on Mac, only Version 16.35 (20030802) and later supports saving a meeting. Otherwise, the saveAsync method fails when called from a meeting in compose mode. For a workaround, see Cannot save a meeting as a draft in Outlook for Mac by using Office JS API.

Errors:

• InvalidAttachmentId: The attachment identifier does not exist.

Examples

Office.context.mailbox.item.saveAsync(
    function callback(result) {
        // Process the result.
    });

// The following is an example of the
// `result` parameter passed to the
// callback function. The `value`
// property contains the item ID of
// the item.
{
    "value": "AAMkADI5...AAA=",
    "status": "succeeded"
}

Asynchronously inserts data into the body or subject of a message.

The setSelectedDataAsync method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. After insertion, the cursor is placed at the end of the inserted content.

setSelectedDataAsync(data: string, options: Office.AsyncContextOptions & CoercionTypeOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.2 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Errors:

• InvalidAttachmentId: The attachment identifier does not exist.

Examples

Office.context.mailbox.item.setSelectedDataAsync("<b>Hello World!</b>", { coercionType : "html" });

Office.context.mailbox.item.setSelectedDataAsync("Hello World!");

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

Office.context.mailbox.item.setSelectedDataAsync("Replaced", function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Selected text has been updated successfully.");
  } else {
    console.error(asyncResult.error);
  }
});

Asynchronously inserts data into the body or subject of a message.

The setSelectedDataAsync method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. After insertion, the cursor is placed at the end of the inserted content.

setSelectedDataAsync(data: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.2 ]

Minimum permission level: read/write item

Applicable Outlook mode: Appointment Organizer

Errors:

• InvalidAttachmentId: The attachment identifier does not exist.