Office.Mailbox interface

Stellt einem Outlook-Add-In Diagnoseinformationen bereit.

Informationen zu den Diagnoseeigenschaften, auf die Sie zugreifen können, finden Sie unter Office.Diagnostics.

diagnostics: Diagnostics;

Eigenschaftswert

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Ab Postfachanforderungssatz 1.5 können Sie auch die Office.context.Diagnose-Eigenschaft verwenden, um ähnliche Informationen zu erhalten.

Beispiele

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

// This function gets a mailbox's diagnostic information, such as Outlook client and version, and logs it to the console.
const diagnostics = Office.context.mailbox.diagnostics;
console.log(`Client application: ${diagnostics.hostName}`);
console.log(`Client version: ${diagnostics.hostVersion}`);

switch (diagnostics.OWAView) {
  case undefined:
    console.log("Current view (Outlook on the web only): Not applicable. An Outlook desktop client is in use.");
    break;
  case Office.MailboxEnums.OWAView.OneColumnNarrow:
    console.log("Current view (Outlook on the web only): Viewed from an older generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.OneColumn:
    console.log("Current view (Outlook on the web only): Viewed from a newer generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.TwoColumns:
    console.log("Current view (Outlook on the web only): Viewed from a tablet");
    break;
  case Office.MailboxEnums.OWAView.ThreeColumns:
    console.log("Current view (Outlook on the web only): Viewed from a desktop computer");
    break;
}

if (Office.context.requirements.isSetSupported("Mailbox", "1.16")) {
  const ewsTokenStatus = diagnostics.ews;
  ewsTokenStatus.getTokenStatusAsync({ isRest: false }, (result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
      console.log(result.error.message);
      return;
    }

    const status = result.value;
    switch (status) {
      case Office.MailboxEnums.TokenStatus.Enabled:
        console.log("EWS token status: EWS callback tokens are enabled.");
        break;
      case Office.MailboxEnums.TokenStatus.Disabled:
        console.log("EWS token status: EWS callback tokens are disabled.");
        break;
      case Office.MailboxEnums.TokenStatus.Removed:
        console.log("EWS token status: The organization has an Exchange Online environment. Legacy Exchange tokens are no longer supported.");
        break;
    }
  });
}

Ruft die URL des EWS-Endpunkts (Exchange-Webdienste) für dieses E-Mail-Konto ab.

ewsUrl: string;

Eigenschaftswert

Hinweise

API-Satz: Postfach 1.1

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

• Ihre App muss über die Berechtigung zum Lesen von Elementen verfügen, die im Manifest angegeben ist, um das ewsUrl Mitglied im Lesemodus aufrufen zu können.

• Im Erstellungsmodus müssen Sie die saveAsync Methode aufrufen, bevor Sie den ewsUrl Member verwenden können. Ihre App muss über Lese-/Schreibberechtigungen verfügen, um die Methode aufzurufen saveAsync .

• Diese Eigenschaft wird in Outlook unter Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook auf Mobilgeräten unterstützte Outlook-JavaScript-APIs.

• Der ewsUrl Wert kann von einem Remotedienst verwendet werden, um EWS-Aufrufe an das Postfach des Benutzers zu senden. Sie können beispielsweise einen Remotedienst erstellen, um Anlagen aus dem ausgewählten Element abzurufen.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

Das Postfachelement. Je nach Kontext, in dem das Add-In geöffnet wurde, kann der Elementtyp variieren. Wenn Sie IntelliSense nur für einen bestimmten Typ oder Modus anzeigen möchten, wandeln Sie dieses Element in einen der folgenden Werte um:

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Wichtig:

• Beachten Sie beim Aufrufen Office.context.mailbox.item einer Nachricht, dass der Lesebereich im Outlook-Client aktiviert sein muss. Anleitungen zum Konfigurieren des Lesebereichs finden Sie unter Verwenden und Konfigurieren des Lesebereichs für die Vorschau von Nachrichten.

• item kann NULL sein, wenn Ihr Add-In das Anheften des Aufgabenbereichs unterstützt. Ausführliche Informationen zur Handhabung finden Sie unter Implementieren eines anheftbaren Aufgabenbereichs in Outlook.

item?: Item & ItemCompose & ItemRead & Message & MessageCompose & MessageRead & Appointment & AppointmentCompose & AppointmentRead;

Eigenschaftswert

Ruft ein Objekt ab, das Methoden zum Verwalten der Kategorien-Master-Liste bereitstellt, die einem Postfach zugeordnet ist.

masterCategories: MasterCategories;

Eigenschaftswert

Hinweise

API-Satz: Postfach 1.8

Mindestberechtigungsstufe: Lese-/Schreibpostfach

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

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

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Master categories:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories in the master list.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const masterCategoriesToAdd = [
  {
    displayName: "TestCategory",
    color: Office.MailboxEnums.CategoryColor.Preset0
  }
];

Office.context.mailbox.masterCategories.addAsync(masterCategoriesToAdd, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully added categories to master list");
  } else {
    console.log("masterCategories.addAsync call failed with error: " + asyncResult.error.message);
  }
});

...

const masterCategoriesToRemove = ["TestCategory"];

Office.context.mailbox.masterCategories.removeAsync(masterCategoriesToRemove, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed categories from master list");
  } else {
    console.log("masterCategories.removeAsync call failed with error: " + asyncResult.error.message);
  }
});

Ruft die URL des REST-Endpunkts für das betreffende E-Mail-Konto ab.

restUrl: string;

Eigenschaftswert

Hinweise

API-Satz: Postfach 1.5

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

• Die Outlook-REST v2.0- und Beta-Endpunkte sind jetzt veraltet. Privat veröffentlichte und von AppSource gehostete Add-Ins können den REST-Dienst jedoch bis zum Ende des erweiterten Supports für Outlook 2019 am 14. Oktober 2025 verwenden. Datenverkehr von diesen Add-Ins wird automatisch zur Ausnahme identifiziert. Diese Ausnahme gilt auch für neue Add-Ins, die nach dem 31. März 2024 entwickelt wurden. Add-Ins können den REST-Dienst zwar bis 2025 verwenden, wir empfehlen Ihnen jedoch dringend, Ihre Add-Ins auf Microsoft Graph zu migrieren. Anleitungen finden Sie unter Vergleichen von Microsoft Graph- und Outlook-REST-API-Endpunkten.

• Ihr Add-In muss die Berechtigung zum Lesen von Elementen im Manifest angegeben haben, um das restUrl Mitglied im Lesemodus aufrufen zu können.

• Im Verfassenmodus müssen Sie die saveAsync-Methode aufrufen, bevor Sie das restUrl-Element verwenden können. Ihr Add-In muss über Lese- /Schreibberechtigungen verfügen, um die Methode aufzurufen saveAsync . In Stellvertretungs- oder freigegebenen Szenarien sollten Sie jedoch stattdessen die targetRestUrl Eigenschaft des SharedProperties-Objekts verwenden (eingeführt in Anforderungssatz 1.8). Weitere Informationen finden Sie im Artikel zu freigegebenen Ordnern und freigegebenen Postfächern .

Beispiele

// Get the URL of the REST endpoint.
const restUrl = Office.context.mailbox.restUrl;
console.log(`REST API URL: ${restUrl}`);

Informationen über den Benutzer, der dem Postfach zugeordnet ist. Dazu gehören der Kontotyp, der Anzeigename, die E-Mail-Adresse und die Zeitzone.

Weitere Informationen finden Sie unter Office.UserProfile

userProfile: UserProfile;

Eigenschaftswert

Fügt einen Ereignishandler für ein unterstütztes Ereignis hinzu. Ereignisse stehen nur in Aufgabenbereich-Add-Ins zur Verfügung.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.5

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig: Die folgenden Ereignisse werden für das Mailbox Objekt unterstützt.

Beispiele

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

function loadNewItem(eventArgs) {
    const item = Office.context.mailbox.item;

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

Fügt einen Ereignishandler für ein unterstütztes Ereignis hinzu. Ereignisse stehen nur in Aufgabenbereich-Add-Ins zur Verfügung.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.5

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig: Die folgenden Ereignisse werden für das Mailbox Objekt unterstützt.

Konvertiert eine unterstützte ID in das Exchange-Webdienste (EWS)-Format.

convertToEwsId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Parameter

Gibt zurück

Hinweise

API-Satz: Mailbox 1.3

Mindestberechtigungsstufe: Eingeschränkt

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

• Legacy-Benutzeridentitätstoken und Rückruftoken von Exchange Online werden nicht mehr unterstützt und sind für alle Microsoft 365-Mandanten deaktiviert. Wenn ein Outlook-Add-In einen delegierten Benutzerzugriff oder eine delegierte Benutzeridentität erfordert, empfehlen wir die Verwendung von MSAL (Microsoft Authentication Library (MSAL)) und der geschachtelten App-Authentifizierung (NAA). Exchange-Benutzeridentitätstoken werden für Exchange lokal weiterhin unterstützt.

• Diese Methode wird in Outlook auf Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook auf Mobilgeräten unterstützte Outlook-JavaScript-APIs.

• Über eine REST-API (z. B. Microsoft Graph) abgerufene Element-IDs verwenden ein anderes Format als das von EWS verwendete Format. Die convertToEwsId Methode konvertiert eine REST-formatierte ID in das richtige Format für EWS.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

Ruft ein Wörterbuch mit Uhrzeitinformationen basierend auf der Zeiteinstellung des lokalen Clients ab.

Die vom Outlook-Client verwendete Zeitzone variiert je nach Plattform. Outlook unter Windows (klassisch) und auf dem Mac verwenden die Zeitzone des Clientcomputers. Outlook im Web und das neue Outlook unter Windows verwenden die im Exchange Admin Center (EAC) festgelegte Zeitzone. Sie sollten Datums- und Uhrzeitwerte bearbeiten, damit die auf der Benutzeroberfläche angezeigten Werte immer den von Benutzer erwarteten Zeitzonen entsprechen.

In Outlook unter Windows (klassisch) und auf Mac gibt die convertToLocalClientTime Methode ein Wörterbuchobjekt zurück, dessen Werte auf die Zeitzone des Clientcomputers festgelegt sind. In Outlook im Web und im neuen Outlook unter Windows gibt die convertToLocalClientTime Methode ein Wörterbuchobjekt zurück, dessen Werte auf die in der Domänenverwaltungskonsole angegebene Zeitzone festgelegt sind.

convertToLocalClientTime(timeValue: Date): LocalClientTime;

Parameter

Gibt zurück

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

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

const time = Office.context.mailbox.item.start;
const localTime = Office.context.mailbox.convertToLocalClientTime(time);
console.log(`Appointment starts (local): ${localTime.month + 1}/${localTime.date}/${localTime.year}, ${localTime.hours}:${localTime.minutes}:${localTime.seconds}`);

Konvertiert eine unterstützte ID in das REST-Format.

convertToRestId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Parameter

Gibt zurück

Hinweise

API-Satz: Mailbox 1.3

Mindestberechtigungsstufe: Eingeschränkt

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

• Diese Methode wird in Outlook auf Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook auf Mobilgeräten unterstützte Outlook-JavaScript-APIs.

• Element-IDs, die über Exchange-Webdienste (Exchange-Webdienste, EWS) oder über die itemId Eigenschaft abgerufen werden, verwenden ein anderes Format als das von REST-APIs verwendete Format (z. B. Microsoft Graph). Die convertToRestId Methode konvertiert eine EWS-formatierte ID in das richtige Format für REST.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

Ruft ein Date Objekt aus einem Wörterbuch ab, das Zeitinformationen enthält.

Die convertToUtcClientTime Methode konvertiert ein Wörterbuch, das ein lokales Datum und eine lokale Uhrzeit enthält, in ein Date Objekt mit den richtigen Werten für das lokale Datum und die lokale Uhrzeit.

convertToUtcClientTime(input: LocalClientTime): Date;

Parameter

Gibt zurück

Ein Date-Objekt der Uhrzeit in UTC.

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

// Represents 3:37 PM PDT on Monday, August 26, 2019.
const input = {
    date: 26,
    hours: 15,
    milliseconds: 2,
    minutes: 37,
    month: 7,
    seconds: 2,
    timezoneOffset: -420,
    year: 2019
};

// result should be a Date object.
const result = Office.context.mailbox.convertToUtcClientTime(input);

// Output should be "2019-08-26T22:37:02.002Z".
console.log(result.toISOString());

Zeigt einen bestehenden Kalendertermin an.

Die displayAppointmentForm Methode öffnet einen vorhandenen Kalendertermin in einem neuen Fenster auf dem Desktop.

In Outlook für Mac können Sie mit dieser Methode einen einzelnen Termin, der nicht Teil einer Serie ist, oder den Master-Termin einer Terminserie anzeigen. Sie können jedoch keine Instance der Serie anzeigen, da Sie nicht auf die Eigenschaften (einschließlich der Element-ID) von Instanzen einer wiederkehrenden Serie zugreifen können.

In Outlook im Web und im neuen Outlook unter Windows wird mit dieser Methode das angegebene Formular nur geöffnet, wenn der Textkörper des Formulars kleiner oder gleich 32K Zeichen ist.

Wenn der angegebene Elementbezeichner keinen vorhandenen Termin identifiziert, wird auf dem Clientcomputer oder -gerät ein leerer Bereich geöffnet, und es wird keine Fehlermeldung zurückgegeben.

displayAppointmentForm(itemId: string): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.1

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig: Diese Methode wird in Outlook auf Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook auf Mobilgeräten unterstützte Outlook-JavaScript-APIs.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = (document.getElementById("itemId") as HTMLInputElement).value;
Office.context.mailbox.displayAppointmentForm(itemId);

Zeigt einen bestehenden Kalendertermin an.

Mit der displayAppointmentFormAsync-Methode wird ein vorhandener Kalendertermin auf dem Desktop in einem neuen Fenster oder auf Mobilgeräten in einem Dialogfeld geöffnet.

In Outlook für Mac können Sie mit dieser Methode einen einzelnen Termin, der nicht Teil einer Serie ist, oder den Master-Termin einer Terminserie anzeigen. Sie können jedoch keine Instance der Serie anzeigen, da Sie nicht auf die Eigenschaften (einschließlich der Element-ID) von Instanzen einer wiederkehrenden Serie zugreifen können.

In Outlook im Web und im neuen Outlook unter Windows wird mit dieser Methode das angegebene Formular nur geöffnet, wenn der Textkörper des Formulars kleiner oder gleich 32K Zeichen ist.

Wenn der angegebene Elementbezeichner keinen vorhandenen Termin identifiziert, wird auf dem Clientcomputer oder -gerät ein leerer Bereich geöffnet, und es wird keine Fehlermeldung zurückgegeben.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.9

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = (document.getElementById("itemId") as HTMLInputElement).value;

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayAppointmentFormAsync(itemId, function(asyncResult) {
  console.log("Result: " + JSON.stringify(asyncResult));
});

Zeigt einen bestehenden Kalendertermin an.

Mit der displayAppointmentFormAsync-Methode wird ein vorhandener Kalendertermin auf dem Desktop in einem neuen Fenster oder auf Mobilgeräten in einem Dialogfeld geöffnet.

In Outlook für Mac können Sie mit dieser Methode einen einzelnen Termin, der nicht Teil einer Serie ist, oder den Master-Termin einer Terminserie anzeigen. Sie können jedoch keine Instance der Serie anzeigen, da Sie nicht auf die Eigenschaften (einschließlich der Element-ID) von Instanzen einer wiederkehrenden Serie zugreifen können.

In Outlook im Web und im neuen Outlook unter Windows wird mit dieser Methode das angegebene Formular nur geöffnet, wenn der Textkörper des Formulars kleiner oder gleich 32K Zeichen ist.

Wenn der angegebene Elementbezeichner keinen vorhandenen Termin identifiziert, wird auf dem Clientcomputer oder -gerät ein leerer Bereich geöffnet, und es wird keine Fehlermeldung zurückgegeben.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.9

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Zeigt eine vorhandene Nachricht an.

Die displayMessageForm Methode öffnet eine vorhandene Meldung in einem neuen Fenster auf dem Desktop.

In Outlook im Web und im neuen Outlook unter Windows wird mit dieser Methode das angegebene Formular nur geöffnet, wenn der Textkörper des Formulars kleiner oder gleich 32K Zeichen ist.

Wenn der angegebene Elementbezeichner keine vorhandene Nachricht identifiziert, wird keine Meldung auf dem Clientcomputer angezeigt, und es wird keine Fehlermeldung zurückgegeben.

displayMessageForm(itemId: string): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.1

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

• Diese Methode wird in Outlook auf Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook auf Mobilgeräten unterstützte Outlook-JavaScript-APIs.

• Verwenden Sie das displayMessageForm nicht mit einer itemId, die einen Termin darstellt. Verwenden Sie die displayAppointmentForm-Methode, um einen vorhandenen Termin anzuzeigen, und displayNewAppointmentForm, um ein Formular zum Erstellen eines neuen Termins anzuzeigen.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = (document.getElementById("itemId") as HTMLInputElement).value;
Office.context.mailbox.displayMessageForm(itemId);

Zeigt eine vorhandene Nachricht an.

Die displayMessageFormAsync-Methode öffnet eine vorhandene Nachricht in einem neuen Fenster auf dem Desktop bzw. in einem Dialogfeld auf Mobilgeräten.

In Outlook im Web und im neuen Outlook unter Windows wird mit dieser Methode das angegebene Formular nur geöffnet, wenn der Textkörper des Formulars kleiner oder gleich 32K Zeichen ist.

Wenn der angegebene Elementbezeichner keine vorhandene Nachricht identifiziert, wird keine Meldung auf dem Clientcomputer angezeigt, und es wird keine Fehlermeldung zurückgegeben.

Verwenden Sie die displayMessageForm ODER-Methode displayMessageFormAsync nicht mit einer itemId, die einen Termin darstellt. Verwenden Sie die displayAppointmentForm ODER-Methode displayAppointmentFormAsync , um einen vorhandenen Termin anzuzeigen, und displayNewAppointmentForm oder displayNewAppointmentFormAsync zum Anzeigen eines Formulars zum Erstellen eines neuen Termins.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.9

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = (document.getElementById("itemId") as HTMLInputElement).value;

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayMessageFormAsync(itemId, function (asyncResult) {
 console.log("Result: " + JSON.stringify(asyncResult));
});

Zeigt eine vorhandene Nachricht an.

Die displayMessageFormAsync-Methode öffnet eine vorhandene Nachricht in einem neuen Fenster auf dem Desktop bzw. in einem Dialogfeld auf Mobilgeräten.

In Outlook im Web und im neuen Outlook unter Windows wird mit dieser Methode das angegebene Formular nur geöffnet, wenn der Textkörper des Formulars kleiner oder gleich 32K Zeichen ist.

Wenn der angegebene Elementbezeichner keine vorhandene Nachricht identifiziert, wird keine Meldung auf dem Clientcomputer angezeigt, und es wird keine Fehlermeldung zurückgegeben.

Verwenden Sie die displayMessageForm ODER-Methode displayMessageFormAsync nicht mit einer itemId, die einen Termin darstellt. Verwenden Sie die displayAppointmentForm ODER-Methode displayAppointmentFormAsync , um einen vorhandenen Termin anzuzeigen, und displayNewAppointmentForm oder displayNewAppointmentFormAsync zum Anzeigen eines Formulars zum Erstellen eines neuen Termins.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.9

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Zeigt ein Formular zum Erstellen eines neuen Kalendertermins an.

Mit der displayNewAppointmentForm-Methode wird ein Formular geöffnet, mit dem der Benutzer einen neuen Termin oder eine Besprechung erstellen kann. Wenn Parameter angegeben wurden, werden die Felder im Terminformular automatisch mit dem Inhalt der Parameter ausgefüllt.

In Outlook im Web und im neuen Outlook unter Windows wird mit dieser Methode immer ein Formular mit einem Teilnehmerfeld angezeigt. Wenn Sie keine Teilnehmer als Eingabeargumente angeben, zeigt die Methode ein Formular mit einer Schaltfläche " Speichern " an. Wenn Sie Teilnehmer angegeben haben, enthält das Formular die Teilnehmer und eine Schaltfläche Senden.

Wenn Sie in Outlook unter Windows (klassisch) und unter Mac Teilnehmer oder Ressourcen im requiredAttendeesParameter , optionalAttendeesoder resources angeben, zeigt diese Methode ein Besprechungsformular mit einer Schaltfläche "Senden " an. Wenn keine Teilnehmer angegeben werden, wird mit dieser Methode ein Terminformular mit der Schaltfläche Speichern & schließen angezeigt.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

displayNewAppointmentForm(parameters: AppointmentForm): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.1

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

Wichtig: Diese Methode wird in Outlook auf Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook auf Mobilgeräten unterstützte Outlook-JavaScript-APIs.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

Office.context.mailbox.displayNewAppointmentForm({
  requiredAttendees: ["bob@contoso.com"] as any,
  optionalAttendees: ["sam@contoso.com"] as any,
  start: start,
  end: end,
  location: "Home",
  subject: "meeting",
  resources: ["projector@contoso.com"] as any,
  body: "Hello World!"
});

Zeigt ein Formular zum Erstellen eines neuen Kalendertermins an.

Mit der displayNewAppointmentFormAsync-Methode wird ein Formular geöffnet, mit dem der Benutzer einen neuen Termin oder eine Besprechung erstellen kann. Wenn Parameter angegeben wurden, werden die Felder im Terminformular automatisch mit dem Inhalt der Parameter ausgefüllt.

In Outlook im Web und im neuen Outlook unter Windows wird mit dieser Methode immer ein Formular mit einem Teilnehmerfeld angezeigt. Wenn Sie keine Teilnehmer als Eingabeargumente angeben, zeigt die Methode ein Formular mit einer Schaltfläche Speichern an. Wenn Sie Teilnehmer angegeben haben, enthält das Formular die Teilnehmer und eine Schaltfläche Senden.

Wenn Sie in Outlook unter Windows (klassisch) und unter Mac Teilnehmer oder Ressourcen im requiredAttendeesParameter , optionalAttendeesoder resources angeben, zeigt diese Methode ein Besprechungsformular mit einer Schaltfläche "Senden " an. Wenn keine Teilnehmer angegeben werden, wird mit dieser Methode ein Terminformular mit der Schaltfläche Speichern & schließen angezeigt.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.9

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new appointment form has been created.
Office.context.mailbox.displayNewAppointmentFormAsync(
  {
    requiredAttendees: ["bob@contoso.com"] as any,
    optionalAttendees: ["sam@contoso.com"] as any,
    start: start,
    end: end,
    location: "Home",
    subject: "meeting",
    resources: ["projector@contoso.com"] as any,
    body: "Hello World!"
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

Zeigt ein Formular zum Erstellen eines neuen Kalendertermins an.

Mit der displayNewAppointmentFormAsync-Methode wird ein Formular geöffnet, mit dem der Benutzer einen neuen Termin oder eine Besprechung erstellen kann. Wenn Parameter angegeben wurden, werden die Felder im Terminformular automatisch mit dem Inhalt der Parameter ausgefüllt.

In Outlook im Web und im neuen Outlook unter Windows wird mit dieser Methode immer ein Formular mit einem Teilnehmerfeld angezeigt. Wenn Sie keine Teilnehmer als Eingabeargumente angeben, zeigt die Methode ein Formular mit einer Schaltfläche Speichern an. Wenn Sie Teilnehmer angegeben haben, enthält das Formular die Teilnehmer und eine Schaltfläche Senden.

Wenn Sie in Outlook unter Windows (klassisch) und unter Mac Teilnehmer oder Ressourcen im requiredAttendeesParameter , optionalAttendeesoder resources angeben, zeigt diese Methode ein Besprechungsformular mit einer Schaltfläche "Senden " an. Wenn keine Teilnehmer angegeben werden, wird mit dieser Methode ein Terminformular mit der Schaltfläche Speichern & schließen angezeigt.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

displayNewAppointmentFormAsync(parameters: AppointmentForm, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.9

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

Zeigt ein Formular zum Erstellen einer neuen Nachricht an.

Die displayNewMessageForm Methode öffnet ein Formular, über das der Benutzer eine neue Nachricht erstellen kann. Wenn Parameter angegeben werden, werden die Felder des Nachrichtenformulars automatisch mit dem Inhalt der Parameter gefüllt.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

displayNewMessageForm(parameters: MessageForm): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.6

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

Office.context.mailbox.displayNewMessageForm({
  toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
  ccRecipients: ["sam@contoso.com"],
  subject: "Outlook add-ins are cool!",
  htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
  attachments: [
    {
      type: "file",
      name: "image.png",
      url: "https://i.imgur.com/9S36xvA.jpg",
      isInline: true
    }
  ]
});

Zeigt ein Formular zum Erstellen einer neuen Nachricht an.

Die displayNewMessageFormAsync Methode öffnet ein Formular, über das der Benutzer eine neue Nachricht erstellen kann. Wenn Parameter angegeben werden, werden die Felder des Nachrichtenformulars automatisch mit dem Inhalt der Parameter gefüllt.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.9

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new message form has been created.
Office.context.mailbox.displayNewMessageFormAsync(
  {
    toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
    ccRecipients: ["sam@contoso.com"],
    subject: "Outlook add-ins are cool!",
    htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
    attachments: [
      {
        type: "file",
        name: "image.png",
        url: "https://i.imgur.com/9S36xvA.jpg",
        isInline: true
      }
    ]
  },
  (asyncResult) => {
    console.log(JSON.stringify(asyncResult));
  }
);

Zeigt ein Formular zum Erstellen einer neuen Nachricht an.

Die displayNewMessageFormAsync Methode öffnet ein Formular, über das der Benutzer eine neue Nachricht erstellen kann. Wenn Parameter angegeben werden, werden die Felder des Nachrichtenformulars automatisch mit dem Inhalt der Parameter gefüllt.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

displayNewMessageFormAsync(parameters: MessageForm, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.9

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

Ruft eine Zeichenfolge ab, die ein Token enthält, das zum Aufrufen von REST-APIs oder Exchange-Webdiensten (Exchange-Webdienste, EWS) verwendet wird.

Die getCallbackTokenAsync-Methode führt einen asynchronen Aufruf zum Abruf eines nicht transparenten Tokens vom Exchange-Server aus, der das Postfach des Benutzers hostet. Die Gültigkeitsdauer des Rückruftokens beträgt 5 Minuten.

Das Token wird als Zeichenfolge in der asyncResult.value Eigenschaft zurückgegeben.

getCallbackTokenAsync(options: Office.AsyncContextOptions & { isRest?: boolean }, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.5

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

• Legacy-Benutzeridentitätstoken und Rückruftoken von Exchange Online werden nicht mehr unterstützt und sind für alle Microsoft 365-Mandanten deaktiviert. Wenn ein Outlook-Add-In einen delegierten Benutzerzugriff oder eine delegierte Benutzeridentität erfordert, empfehlen wir die Verwendung von MSAL (Microsoft Authentication Library (MSAL)) und der geschachtelten App-Authentifizierung (NAA). Exchange-Benutzeridentitätstoken werden für Exchange lokal weiterhin unterstützt.

• Die Outlook-REST v2.0- und Beta-Endpunkte sind jetzt veraltet. Privat veröffentlichte und von AppSource gehostete Add-Ins können den REST-Dienst jedoch bis zum Ende des erweiterten Supports für Outlook 2019 am 14. Oktober 2025 verwenden. Datenverkehr von diesen Add-Ins wird automatisch zur Ausnahme identifiziert. Diese Ausnahme gilt auch für neue Add-Ins, die nach dem 31. März 2024 entwickelt wurden. Add-Ins können den REST-Dienst zwar bis 2025 verwenden, wir empfehlen Ihnen jedoch dringend, Ihre Add-Ins auf Microsoft Graph zu migrieren. Anleitungen finden Sie unter Vergleichen von Microsoft Graph- und Outlook-REST-API-Endpunkten.

• Um festzustellen, ob REST- oder EWS-Token in einer organization verfügbar sind, rufen Sie Office.context.mailbox.diagnostics.ews.getTokenStatusAsyncauf. Die getTokenStatusAsync Methode steht zur Vorschau in Outlook im Web und Windows (neue und klassische Version 2510, Build 19328.20000 und höher)) zur Verfügung.

• Diese Methode wird nicht unterstützt, wenn Sie ein Add-In in ein Outlook.com- oder Gmail-Postfach laden.

• Diese Methode wird nur im Lesemodus in Outlook unter Android und iOS unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook auf Mobilgeräten unterstützte Outlook-JavaScript-APIs.

• EWS-Vorgänge werden in Add-Ins, die in Outlook unter iOS und Android ausgeführt werden, nicht unterstützt. Ein REST-Token wird in Outlook Mobile-Clients immer zurückgegeben, auch wenn options.isRest es auf falsefestgelegt ist.

• Für das Aufrufen der getCallbackTokenAsync Methode im Lesemodus ist eine Mindestberechtigungsstufe von read item erforderlich.

• Wenn Sie die getCallbackTokenAsync Methode im Kompositionsmodus aufrufen, müssen Sie das Element gespeichert haben. Die saveAsync Methode erfordert eine Mindestberechtigungsstufe von Lese-/Schreibelementen.

• Anleitungen zu Stellvertretungs- oder freigegebenen Szenarien finden Sie im Artikel zu freigegebenen Ordnern und freigegebenen Postfächern .

REST-Token

Wenn ein REST-Token angefordert wird (options.isRest = true), funktioniert das resultierende Token nicht zur Authentifizierung von EWS-Aufrufen. Der Bereich des Tokens ist auf den schreibgeschützten Zugriff auf das aktuelle Element und seine Anlagen beschränkt, es sei denn, das Add-In hat die Lese-/Schreibberechtigung für das Postfach in seinem Manifest festgelegt. Wenn die Lese-/Schreibberechtigung für das Postfach angegeben ist, gewährt das resultierende Token Lese-/Schreibzugriff auf E-Mail, Kalender und Kontakte, einschließlich der Möglichkeit, E-Mails zu senden.

Das Add-In sollte die Eigenschaft restUrl verwenden, um die korrekte URL für REST-API-Aufrufe zu ermitteln.

Diese API funktioniert für die folgenden Bereiche.

• Mail.ReadWrite

• Mail.Send

• Calendars.ReadWrite

• Contacts.ReadWrite

EWS-Tokens

Wenn ein EWS-Token angefordert wird (options.isRest = false), funktioniert das resultierende Token nicht zur Authentifizierung von REST-API-Aufrufen. Der Bereich des Tokens ist auf den Zugriff auf das aktuelle Element beschränkt.

Das Add-In sollte die Eigenschaft ewsUrl verwenden, um die korrekte URL für EWS-Aufrufe zu ermitteln.

Sie können sowohl das Token als auch einen Anlagenbezeichner oder Elementbezeichner an ein externes System übergeben. Dieses System verwendet das Token als Bearerautorisierungstoken, um den GetAttachment-Vorgang oder GetItem-Vorgang der Exchange-Webdienste (EWS) aufzurufen, um eine Anlage oder ein Element zurückzugeben. Sie können beispielsweise einen Remotedienst erstellen, um Anlagen aus dem ausgewählten Element abzurufen.

Fehler:

Wenn Ihr Aufruf fehlschlägt, verwenden Sie die Eigenschaft asyncResult.Diagnose, um Details zum Fehler anzuzeigen.

• GenericTokenError: An internal error has occurred.- In Exchange Online-Umgebungen tritt dieser Fehler auf, wenn das Token nicht abgerufen werden kann, weil Legacy-Exchange-Token für Outlook-Add-Ins deaktiviert sind. Es wird empfohlen, NAA als Single-Sign-On-Lösung für Ihr Add-In zu verwenden.

• HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.

• InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.- In Exchange Online-Umgebungen tritt dieser Fehler auf, wenn das Token nicht abgerufen werden kann, weil Legacy-Exchange-Token für Outlook-Add-Ins deaktiviert sind. Es wird empfohlen, NAA als Single-Sign-On-Lösung für Ihr Add-In zu verwenden.

• NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

Ruft eine Zeichenfolge ab, die einen Token enthält, der verwendet wird, um eine Anlage oder ein Element von einem Exchange Server abzurufen.

Die getCallbackTokenAsync-Methode führt einen asynchronen Aufruf zum Abruf eines nicht transparenten Tokens vom Exchange-Server aus, der das Postfach des Benutzers hostet. Die Gültigkeitsdauer des Rückruftokens beträgt 5 Minuten.

Das Token wird als Zeichenfolge in der asyncResult.value Eigenschaft zurückgegeben.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Alle unterstützen den Lesemodus; Introduction Mailbox 1.3 Unterstützung des Modus "Compose"

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

• Legacy-Benutzeridentitätstoken und Rückruftoken von Exchange Online werden nicht mehr unterstützt und sind für alle Microsoft 365-Mandanten deaktiviert. Wenn ein Outlook-Add-In einen delegierten Benutzerzugriff oder eine delegierte Benutzeridentität erfordert, empfehlen wir die Verwendung von MSAL (Microsoft Authentication Library (MSAL)) und der geschachtelten App-Authentifizierung (NAA). Exchange-Benutzeridentitätstoken werden für Exchange lokal weiterhin unterstützt.

• Sie können sowohl das Token als auch einen Anlagenbezeichner oder Elementbezeichner an ein externes System übergeben. Dieses System verwendet das Token als Bearerautorisierungstoken, um den GetAttachment- oder GetItem-Vorgang der Exchange-Webdienste (EWS) aufzurufen, um eine Anlage oder ein Element zurückzugeben. Sie können beispielsweise einen Remotedienst erstellen, um Anlagen aus dem ausgewählten Element abzurufen.

• Um festzustellen, ob REST- oder EWS-Token in einer organization verfügbar sind, rufen Sie Office.context.mailbox.diagnostics.ews.getTokenStatusAsyncauf. Die getTokenStatusAsync Methode steht zur Vorschau in Outlook im Web und Windows (neue und klassische Version 2510, Build 19328.20000 und höher)) zur Verfügung.

• Für das Aufrufen der getCallbackTokenAsync Methode im Lesemodus ist eine Mindestberechtigungsstufe von read item erforderlich.

• Wenn Sie die getCallbackTokenAsync Methode im Kompositionsmodus aufrufen, müssen Sie das Element gespeichert haben. Die saveAsync Methode erfordert eine Mindestberechtigungsstufe von Lese-/Schreibelementen.

• Diese Methode wird in Outlook auf Android oder iOS nicht unterstützt. EWS-Vorgänge werden in Add-Ins, die in Outlook auf mobilen Clients ausgeführt werden, nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook auf Mobilgeräten unterstützte Outlook-JavaScript-APIs.

• Diese Methode wird nicht unterstützt, wenn Sie ein Add-In in ein Outlook.com- oder Gmail-Postfach laden.

• Anleitungen zu Stellvertretungs- oder freigegebenen Szenarien finden Sie im Artikel zu freigegebenen Ordnern und freigegebenen Postfächern .

Fehler:

Wenn Ihr Aufruf fehlschlägt, verwenden Sie die Eigenschaft asyncResult.Diagnose, um Details zum Fehler anzuzeigen.

• GenericTokenError: An internal error has occurred.- In Exchange Online-Umgebungen tritt dieser Fehler auf, wenn das Token nicht abgerufen werden kann, weil Legacy-Exchange-Token für Outlook-Add-Ins deaktiviert sind. Es wird empfohlen, NAA als Single-Sign-On-Lösung für Ihr Add-In zu verwenden.

• HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.

• InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.- In Exchange Online-Umgebungen tritt dieser Fehler auf, wenn das Token nicht abgerufen werden kann, weil Legacy-Exchange-Token für Outlook-Add-Ins deaktiviert sind. Es wird empfohlen, NAA als Single-Sign-On-Lösung für Ihr Add-In zu verwenden.

• NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/user-callback-token.yaml

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

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

Gibt "true" zurück, wenn das aktuelle Postfach von Microsoft Intune verwaltet wird.

getIsIdentityManaged(): boolean;

Gibt zurück

"True", wenn das aktuelle Postfach von Microsoft Intune verwaltet wird.

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose, Read

Wichtig: Diese Methode wird nur in Outlook unter Android und iOS ab Version 4.2443.0 unterstützt. Weitere Informationen zu APIs, die in Outlook auf Mobilgeräten unterstützt werden, finden Sie unter Outlook-JavaScript-APIs, die in Outlook auf Mobilgeräten unterstützt werden.

Fehler:

• MAMServiceNotAvailable : Der Client kann die Richtlinie für die mobile Anwendungsverwaltung (Mobile Application Management, MAM) nicht abrufen.

Beispiele

// Checks if the mailbox is managed by Microsoft Intune.
const isIdentityManaged = Office.context.mailbox.getIsIdentityManaged();
console.log(`Intune-managed mailbox: ${isIdentityManaged}`);

Gibt "true" zurück, wenn die Intune MAM-Richtlinie (Mobile Application Management) eines organization einem Add-In den Zugriff auf Daten vom angegebenen Speicherort gestattet.

getIsOpenFromLocationAllowed(openLocation: MailboxEnums.OpenLocation): boolean;

Parameter

Gibt zurück

"True", wenn die Intune MAM-Richtlinie einer Organisation einem Add-In den Zugriff auf Daten vom angegebenen Speicherort erlaubt.

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose, Read

Wichtig: Diese Methode wird nur in Outlook unter Android und iOS ab Version 4.2443.0 unterstützt. Weitere Informationen zu APIs, die in Outlook auf Mobilgeräten unterstützt werden, finden Sie unter Outlook-JavaScript-APIs, die in Outlook auf Mobilgeräten unterstützt werden.

Fehler:

• InvalidOpenLocationInput : Der Wert des angegebenen Standorts ist ungültig.

• MAMServiceNotAvailable : Der Client kann die MAM-Richtlinie nicht abrufen.

Beispiele

// Checks if the add-in can access data from the device's photo library.
const isOpenFromPhotoLibraryAllowed = Office.context.mailbox.getIsOpenFromLocationAllowed(Office.MailboxEnums.OpenLocation.PhotoLibrary);
if (isOpenFromPhotoLibraryAllowed) {
    console.log("Access to the photo library is allowed.");
    // Do something.
} else {
    console.log("Access to the photo library isn't allowed.");
}

Gibt "true" zurück, wenn die Intune-Richtlinie für die mobile Anwendungsverwaltung (Mobile Application Management, MAM) einer Organisation einem Add-In das Speichern von Daten am angegebenen Speicherort erlaubt.

getIsSaveToLocationAllowed(saveLocation: MailboxEnums.SaveLocation): boolean;

Parameter

Gibt zurück

"True", wenn die Intune MAM-Richtlinie einer organization einem Add-In das Speichern von Daten am angegebenen Speicherort erlaubt.

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose, Read

Wichtig: Diese Methode wird nur in Outlook unter Android und iOS ab Version 4.2443.0 unterstützt. Weitere Informationen zu APIs, die in Outlook auf Mobilgeräten unterstützt werden, finden Sie unter Outlook-JavaScript-APIs, die in Outlook auf Mobilgeräten unterstützt werden.

Fehler:

• InvalidSaveLocationInput : Der Wert des angegebenen Standorts ist ungültig.

• MAMServiceNotAvailable : Der Client kann die MAM-Richtlinie nicht abrufen.

Beispiele

// Checks if the add-in can save data to SharePoint.
const isSaveToSharePointAllowed = Office.context.mailbox.getIsSaveToLocationAllowed(Office.MailboxEnums.SaveLocation.SharePoint);
if (isSaveToSharePointAllowed) {
    console.log("Saving to SharePoint is allowed.");
    // Do something.
} else {
    console.log("Saving to SharePoint isn't allowed.");
}

Ruft die aktuell ausgewählten Nachrichten ab, für die ein Add-In aktiviert und Operationen ausgeführt werden kann. Ein Add-In kann auf maximal 100 Nachrichten gleichzeitig aktiviert werden. Weitere Informationen zur Mehrfachauswahl von Elementen finden Sie unter Aktivieren Ihres Outlook-Add-Ins für mehrere Nachrichten.

getSelectedItemsAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Mailbox 1.13

Mindestberechtigungsstufe: Lese-/Schreibpostfach

Anwendbarer Outlook-Modus: Compose, Read

Wichtig: Diese Methode gilt nur für Nachrichten.

Ruft die aktuell ausgewählten Nachrichten ab, für die ein Add-In aktiviert und Operationen ausgeführt werden kann. Ein Add-In kann auf maximal 100 Nachrichten gleichzeitig aktiviert werden. Weitere Informationen zur Mehrfachauswahl von Elementen finden Sie unter Aktivieren Ihres Outlook-Add-Ins für mehrere Nachrichten.

getSelectedItemsAsync(callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Mailbox 1.13

Mindestberechtigungsstufe: Lese-/Schreibpostfach

Anwendbarer Outlook-Modus: Compose, Read

Wichtig: Diese Methode gilt nur für Nachrichten.

Beispiele

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

// Retrieves the selected messages' properties and logs them to the console.
Office.context.mailbox.getSelectedItemsAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  asyncResult.value.forEach((message) => {
    console.log(`Item ID: ${message.itemId}`);
    console.log(`Conversation ID: ${message.conversationId}`);
    console.log(`Internet message ID: ${message.internetMessageId}`);
    console.log(`Subject: ${message.subject}`);
    console.log(`Item type: ${message.itemType}`);
    console.log(`Item mode: ${message.itemMode}`);
    console.log(`Has attachment: ${message.hasAttachment}`);
  });
});

Ruft ein Token ab, das den Benutzer und das Office-Add-In identifiziert.

Das Token wird als Zeichenfolge in der asyncResult.value Eigenschaft zurückgegeben.

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

Parameter

Gibt zurück

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

• Legacy-Benutzeridentitätstoken und Rückruftoken von Exchange Online werden nicht mehr unterstützt und sind für alle Microsoft 365-Mandanten deaktiviert. Wenn ein Outlook-Add-In einen delegierten Benutzerzugriff oder eine delegierte Benutzeridentität erfordert, empfehlen wir die Verwendung von MSAL (Microsoft Authentication Library (MSAL)) und der geschachtelten App-Authentifizierung (NAA). Exchange-Benutzeridentitätstoken werden für Exchange lokal weiterhin unterstützt.

• Die getUserIdentityTokenAsync Methode gibt ein Token zurück, mit dem Sie das Add-In und den Benutzer bei einem externen System identifizieren und authentifizieren können.

• Diese Methode wird nicht unterstützt, wenn Sie ein Add-In in ein Outlook.com- oder Gmail-Postfach laden.

Fehler:

Wenn Ihr Aufruf fehlschlägt, verwenden Sie die Eigenschaft asyncResult.Diagnose, um Details zum Fehler anzuzeigen.

• GenericTokenError: An internal error has occurred.- In Exchange Online-Umgebungen tritt dieser Fehler auf, wenn das Token nicht abgerufen werden kann, weil Legacy-Exchange-Token für Outlook-Add-Ins deaktiviert sind. Es wird empfohlen, NAA als Single-Sign-On-Lösung für Ihr Add-In zu verwenden.

• HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.

• InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.- In Exchange Online-Umgebungen tritt dieser Fehler auf, wenn das Token nicht abgerufen werden kann, weil Legacy-Exchange-Token für Outlook-Add-Ins deaktiviert sind. Es wird empfohlen, NAA als Single-Sign-On-Lösung für Ihr Add-In zu verwenden.

• NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/user-identity-token.yaml

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

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

Lädt ein einzelnes E-Mail-Element anhand seiner Exchange-Webdienste (EWS)-ID. Ruft dann ein Objekt ab, das die Eigenschaften und Methoden des geladenen Elements bereitstellt.

loadItemByIdAsync(itemId: string, options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<LoadedMessageCompose | LoadedMessageRead>) => void): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.15

Mindestberechtigungsstufe: Lese-/Schreibpostfach

Anwendbarer Outlook-Modus: Compose, Read

Wichtig:

• Diese Methode gilt nur für Nachrichten.

• Wenn Sie die Element-Multiselect-Funktion implementieren, rufen Sie Office.context.mailbox.getSelectedItemsAsync auf, um die Element-IDs jedes ausgewählten Elements abzurufen, damit sie einzeln geladen werden können.

• Bevor Sie die loadItemByIdAsync Methode mit der Mehrfachauswahl für Elemente implementieren, ermitteln Sie, ob Sie bereits über den Office.context.mailbox.getSelectedItemsAsync Aufruf auf die erforderlichen Eigenschaften des ausgewählten Elements zugreifen können. Wenn Sie können, müssen Sie nicht anrufen loadItemByIdAsync.

• Es kann immer nur jeweils ein E-Mail-Element geladen werden. Wenn Sie implementieren loadItemByIdAsync, müssen Sie nach der Verarbeitung des Elements aufrufen unloadAsync . Dies muss vor dem Aufruf loadItemByIdAsync eines anderen Elements erfolgen.

• Die loadItemByIdAsync Methode kann nur für Nachrichten im selben Postfach aufgerufen werden.

Beispiele

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

async function getSenderEmailAddress(item) {
  const itemId = item.itemId;
  await new Promise<void>((resolve) => {
    Office.context.mailbox.loadItemByIdAsync(itemId, (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(result.error.message);
        resolve();
        return;
      }

      const loadedItem = result.value;
      const sender = (loadedItem.from as any).emailAddress;
      appendToListItem(sender);

      // Unload the current message before processing another selected message.
      loadedItem.unloadAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          resolve();
          return;
        }

        resolve();
      });
    });
  });
}

Lädt ein einzelnes E-Mail-Element anhand seiner Exchange-Webdienste (EWS)-ID. Ruft dann ein Objekt ab, das die Eigenschaften und Methoden des geladenen Elements bereitstellt.

loadItemByIdAsync(itemId: string, callback: (asyncResult: Office.AsyncResult<LoadedMessageCompose | LoadedMessageRead>) => void): void;

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.15

Mindestberechtigungsstufe: Lese-/Schreibpostfach

Anwendbarer Outlook-Modus: Compose, Read

Wichtig:

• Diese Methode gilt nur für Nachrichten.

• Wenn Sie die Element-Multiselect-Funktion implementieren, rufen Sie Office.context.mailbox.getSelectedItemsAsync auf, um die Element-IDs jedes ausgewählten Elements abzurufen, damit sie einzeln geladen werden können.

• Bevor Sie die loadItemByIdAsync Methode mit der Mehrfachauswahl für Elemente implementieren, ermitteln Sie, ob Sie bereits über den Office.context.mailbox.getSelectedItemsAsync Aufruf auf die erforderlichen Eigenschaften des ausgewählten Elements zugreifen können. Wenn Sie können, müssen Sie nicht anrufen loadItemByIdAsync.

• Es kann immer nur jeweils ein E-Mail-Element geladen werden. Wenn Sie implementieren loadItemByIdAsync, müssen Sie nach der Verarbeitung des Elements aufrufen unloadAsync . Dies muss vor dem Aufruf loadItemByIdAsync eines anderen Elements erfolgen.

• Die loadItemByIdAsync Methode kann nur für Nachrichten im selben Postfach aufgerufen werden.

Sendet eine asynchrone Anforderung an einen Exchange-Webdienstedienst (EWS) auf dem Exchange-Server, der das Postfach des Benutzers hostet.

Die makeEwsRequestAsync-Methode sendet eine EWS-Anforderung für das Add-In zu Exchange.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.1

Mindestberechtigungsstufe: Lese-/Schreibpostfach

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

• Legacy-Benutzeridentitätstoken und Rückruftoken von Exchange Online werden nicht mehr unterstützt und sind für alle Microsoft 365-Mandanten deaktiviert. Wenn ein Outlook-Add-In einen delegierten Benutzerzugriff oder eine delegierte Benutzeridentität erfordert, empfehlen wir die Verwendung von MSAL (Microsoft Authentication Library (MSAL)) und der geschachtelten App-Authentifizierung (NAA). Exchange-Benutzeridentitätstoken werden für Exchange lokal weiterhin unterstützt.

• Um die makeEwsRequestAsync Methode für EWS-Anforderungen zu aktivieren, muss der Serveradministrator auf auf dem Clientzugriffsserver EWS-Verzeichnis festlegen OAuthAuthenticationtrue .

• Ihr Add-In muss über die Lese-/Schreibberechtigung für das Postfach verfügen, um diese makeEwsRequestAsync Methode verwenden zu können. Informationen zur Verwendung der Lese- /Schreibpostfachberechtigung und der EWS-Vorgänge, die Sie mit der makeEwsRequestAsync Methode aufrufen können, finden Sie unter Angeben von Berechtigungen für den Mail-Add-In-Zugriff auf das Postfach des Benutzers.

• Wenn Ihr Add-In auf mit Ordnern verknüpfte Elemente zugreifen muss oder seine XML-Anforderung die UTF-8-Codierung (\<?xml version="1.0" encoding="utf-8"?\>) angeben muss, muss es stattdessen Microsoft Graph oder REST-APIs verwenden, um auf das Postfach des Benutzers zuzugreifen.

• Diese Methode wird in Outlook auf Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook auf Mobilgeräten unterstützte Outlook-JavaScript-APIs.

• Diese Methode wird nicht unterstützt, wenn das Add-In in ein Gmail-Postfach geladen wird.

• Wenn Sie die makeEwsRequestAsync Methode in Add-Ins verwenden, die in Outlook-Versionen vor Version 15.0.4535.1004 ausgeführt werden, müssen Sie den Codierungswert auf ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>) festlegen. Verwenden Sie die mailbox.diagnostics.hostVersion Eigenschaft, um die Version eines Outlook-Clients zu ermitteln. Sie müssen den Codierungswert nicht festlegen, wenn Ihr Add-In in Outlook im Web und dem neuen Outlook unter Windows ausgeführt wird. Verwenden Sie die mailbox.diagnostics.hostName Eigenschaft, um den Outlook-Client zu ermitteln, auf dem das Add-In ausgeführt wird.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/get-icaluid-as-attendee.yaml

const ewsId = Office.context.mailbox.item.itemId;
const request = `<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Header><t:RequestServerVersion Version="Exchange2013" /></soap:Header>
      <soap:Body>
        <m:GetItem>
          <m:ItemShape>
            <t:BaseShape>AllProperties</t:BaseShape>
          </m:ItemShape >
          <m:ItemIds>
            <t:ItemId Id="${ewsId}" />
          </m:ItemIds>
        </m:GetItem>
      </soap:Body>
    </soap:Envelope>`;

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

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

...

const request = '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">' +
    '  <soap:Header><t:RequestServerVersion Version="Exchange2010" /></soap:Header>' +
    '  <soap:Body>' +
    '    <m:CreateItem MessageDisposition="SendAndSaveCopy">' +
    '      <m:SavedItemFolderId><t:DistinguishedFolderId Id="sentitems" /></m:SavedItemFolderId>' +
    '      <m:Items>' +
    '        <t:Message>' +
    '          <t:Subject>Hello, Outlook!</t:Subject>' +
    '          <t:Body BodyType="HTML">This message was sent from a ScriptLab code sample, used from ' + Office.context.mailbox.diagnostics.hostName + ', version ' + Office.context.mailbox.diagnostics.hostVersion + '!</t:Body>' +
    '          <t:ToRecipients>' +
    '            <t:Mailbox><t:EmailAddress>' + Office.context.mailbox.userProfile.emailAddress + '</t:EmailAddress></t:Mailbox>' +
    '          </t:ToRecipients>' +
    '        </t:Message>' +
    '      </m:Items>' +
    '    </m:CreateItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(`Failed to make EWS request: ${result.error.message}.`);
        return;
    }
    console.log(result.value);
});

Entfernt die Ereignishandler für einen unterstützten Ereignistyp. Ereignisse stehen nur in Aufgabenbereich-Add-Ins zur Verfügung.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.5

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig: Die folgenden Ereignisse werden für das Mailbox Objekt unterstützt.

Entfernt die Ereignishandler für einen unterstützten Ereignistyp. Ereignisse stehen nur in Aufgabenbereich-Add-Ins zur Verfügung.

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

Parameter

Gibt zurück

Hinweise

API-Satz: Postfach 1.5

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig: Die folgenden Ereignisse werden für das Mailbox Objekt unterstützt.

Beispiele

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

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