Office.Mailbox interface

Proporciona información de diagnóstico a un complemento de Outlook.

Contiene los siguientes miembros.

• hostName (cadena): cadena que representa el nombre de la aplicación de Office. Debe ser uno de los siguientes valores: Outlook,newOutlookWindows , OutlookWebApp, OutlookIOSo .OutlookAndroid Nota: El valor "Outlook" se devuelve para Outlook en Windows (clásico) y en Mac.

• hostVersion(cadena): cadena que representa la versión de la aplicación de Office o la Exchange Server (por ejemplo, "15.0.468.0"). Si el complemento de correo se ejecuta en Outlook en Windows (clásico), en Mac o en dispositivos móviles, la hostVersion propiedad devuelve la versión del cliente de Outlook. En Outlook en la Web y nueva Outlook en Windows, la propiedad devuelve la versión del Exchange Server.

• OWAView(MailboxEnums.OWAView o cadena): enumeración (o literal de cadena) que representa la vista actual de Outlook en la Web. Si la aplicación no está Outlook en la Web, el acceso a esta propiedad da como resultado undefined. Outlook en la Web tiene tres vistas ( -OneColumn mostradas cuando la pantalla es estrecha, TwoColumns - mostradas cuando la pantalla es más ancha y ThreeColumns - mostradas cuando la pantalla es ancha) que corresponden al ancho de la pantalla y a la ventana, y el número de columnas que se pueden mostrar.

Más información en Office.Diagnostics.

diagnostics: Diagnostics;

Valor de propiedad

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

A partir del conjunto de requisitos de buzón 1.5, también puede usar la propiedad Office.context.diagnostics para obtener información similar.

Ejemplos

// 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;
}

Obtiene la dirección URL del punto de conexión de Servicios Web Exchange (EWS) para esta cuenta de correo electrónico.

ewsUrl: string;

Valor de propiedad

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

• La aplicación debe tener el permiso de elemento de lectura especificado en su manifiesto para llamar al ewsUrl miembro en modo de lectura.

• En el modo de redacción, debe llamar al saveAsync método antes de poder usar el ewsUrl miembro. La aplicación debe tener permisos de elemento de lectura y escritura para llamar al saveAsync método .

• Esta propiedad no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

• El valor ewsUrl puede usarse por un servicio remoto para realizar llamadas EWS al buzón del usuario. Por ejemplo, puede crear un servicio remoto para obtener datos adjuntos del elemento seleccionado.

Ejemplos

// 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);

Elemento de buzón de correo. Dependiendo del contexto en el que se abra el complemento, el tipo de elemento puede variar. Si desea ver IntelliSense solo para un tipo o modo específico, convierta este elemento en uno de los siguientes:

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Importante:

• Al llamar a Office.context.mailbox.item en un mensaje, tenga en cuenta que el panel de lectura del cliente de Outlook debe estar activado. Para obtener instrucciones sobre cómo configurar el panel de lectura, consulte Uso y configuración del panel de lectura para obtener una vista previa de los mensajes.

• item puede ser null si el complemento admite el anclaje del panel de tareas. Para obtener más información sobre cómo controlar, vea Implementar un panel de tareas anclable en Outlook.

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

Valor de propiedad

Obtiene un objeto que proporciona métodos para administrar la lista maestra de categorías asociada a un buzón.

masterCategories: MasterCategories;

Valor de propiedad

Comentarios

[ Conjunto de API: Buzón 1.8 ]

Nivel mínimo de permiso: buzón de lectura y escritura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// 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);
  }
});

Obtiene la URL del punto de conexión REST para esta cuenta de correo electrónico.

restUrl: string;

Valor de propiedad

Comentarios

[ Conjunto de API: Buzón 1.5 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

• Los puntos de conexión REST v2.0 y beta de Outlook ahora están en desuso. Sin embargo, los complementos hospedados en AppSource y de publicación privada pueden usar el servicio REST hasta que finalice el soporte extendido para Outlook 2019 el 14 de octubre de 2025. El tráfico de estos complementos se identifica automáticamente para la exención. Esta exención también se aplica a los nuevos complementos desarrollados a partir del 31 de marzo de 2024. Aunque los complementos pueden usar el servicio REST hasta 2025, le recomendamos encarecidamente que migre los complementos para usar Microsoft Graph. Para obtener instrucciones, consulte Comparación de puntos de conexión de LA API REST de Microsoft Graph y Outlook.

• El complemento debe tener el permiso de elemento de lectura especificado en su manifiesto para llamar al restUrl miembro en modo de lectura.

• En el modo de redacción debe llamar al método saveAsync antes de poder usar el miembro restUrl. El complemento debe tener permisos de elemento de lectura y escritura para llamar al saveAsync método . Sin embargo, en escenarios de delegación o compartidos, en su lugar debe usar la targetRestUrl propiedad del objeto SharedProperties (introducida en el conjunto de requisitos 1.8). Para obtener más información, consulte el artículo carpetas compartidas y buzón compartido .

Ejemplos

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

Información sobre el usuario asociado al buzón de correo. Esto incluye el tipo de cuenta, el nombre para mostrar, la dirección de correo electrónico y la zona horaria.

Más información en Office.UserProfile

userProfile: UserProfile;

Valor de propiedad

Agrega un controlador de eventos para un evento admitido. Nota: Los eventos solo están disponibles con la implementación del panel de tareas.

Para ver los eventos admitidos, consulte la sección Eventos del modelo de objetos de buzón.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.5 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

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);
    }
}

Agrega un controlador de eventos para un evento admitido. Nota: Los eventos solo están disponibles con la implementación del panel de tareas.

Para ver los eventos admitidos, consulte la sección Eventos del modelo de objetos de buzón.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.5 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Convierte un identificador admitido en el formato de servicios web de Exchange (EWS).

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.3 ]

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Importante:

• Los tokens de identidad de usuario Exchange Online heredados y los tokens de devolución de llamada ya no se admiten y se desactivan en todos los inquilinos de Microsoft 365. Si un complemento de Outlook requiere acceso de usuario delegado o identidad de usuario, se recomienda usar MSAL (Biblioteca de autenticación de Microsoft) y la autenticación de aplicaciones anidadas (NAA). Los tokens de identidad de usuario de Exchange siguen siendo compatibles con Exchange local.

• Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

• Los identificadores de elemento recuperados a través de una API REST (como Microsoft Graph) usan un formato diferente al que usa EWS. El método convertToEwsId convierte un identificador con formato REST al formato adecuado para EWS.

Ejemplos

// 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);

Obtiene un diccionario con información de tiempo en el tiempo del cliente local.

La zona horaria usada por el cliente de Outlook varía según la plataforma. Outlook en Windows (clásico) y en Mac usan la zona horaria del equipo cliente. Outlook en la Web y la nueva Outlook en Windows usan la zona horaria establecida en el Centro de Administración de Exchange (EAC). Debería tratar los valores de fecha y hora de modo que los valores que aparezcan en la interfaz de usuario sean siempre coherentes con la zona horaria que el usuario espera.

En Outlook en Windows (clásico) y en Mac, el convertToLocalClientTime método devuelve un objeto de diccionario con los valores establecidos en la zona horaria del equipo cliente. En Outlook en la Web y nueva Outlook en Windows, el convertToLocalClientTime método devuelve un objeto de diccionario con los valores establecidos en la zona horaria especificada en el EAC.

convertToLocalClientTime(timeValue: Date): LocalClientTime;

Parámetros

Devoluciones

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

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

Convierte un identificador admitido en formato REST.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.3 ]

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Importante:

• Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

• Los identificadores de elemento recuperados a través de Exchange Web Services (EWS) o a través de la itemId propiedad usan un formato diferente al que usan las API REST (como Microsoft Graph). El método convertToRestId convierte un identificador con formato EWS al formato adecuado para REST.

Ejemplos

// 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);

Obtiene un Date objeto de un diccionario que contiene información de hora.

El convertToUtcClientTime método convierte un diccionario que contiene una fecha y hora locales en un Date objeto con los valores correctos para la fecha y hora locales.

convertToUtcClientTime(input: LocalClientTime): Date;

Parámetros

Devoluciones

Objeto Date con el tiempo expresado en UTC.

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// 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());

Muestra una cita de calendario existente.

El displayAppointmentForm método abre una cita de calendario existente en una nueva ventana del escritorio.

En Outlook en Mac, puede usar este método para mostrar una sola cita que no forme parte de una serie periódica o la cita maestra de una serie periódica. Sin embargo, no se puede mostrar una instancia de la serie porque no se puede acceder a las propiedades (incluido el identificador de elemento) de las instancias de una serie periódica.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica una cita existente, se abre un panel en blanco en el equipo o dispositivo cliente y no se devuelve ningún mensaje de error.

displayAppointmentForm(itemId: string): void;

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante: Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Ejemplos

// 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);

Muestra una cita de calendario existente.

El método displayAppointmentFormAsync abre una cita de calendario existente en una nueva ventana del escritorio o en un cuadro de diálogo en los dispositivos móviles.

En Outlook en Mac, puede usar este método para mostrar una sola cita que no forme parte de una serie periódica o la cita maestra de una serie periódica. Sin embargo, no se puede mostrar una instancia de la serie porque no se puede acceder a las propiedades (incluido el identificador de elemento) de las instancias de una serie periódica.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica una cita existente, se abre un panel en blanco en el equipo o dispositivo cliente y no se devuelve ningún mensaje de error.

Nota: Este método no se admite en Outlook en iOS ni en Android.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.9 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// 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));
});

Muestra una cita de calendario existente.

El método displayAppointmentFormAsync abre una cita de calendario existente en una nueva ventana del escritorio o en un cuadro de diálogo en los dispositivos móviles.

En Outlook en Mac, puede usar este método para mostrar una sola cita que no forme parte de una serie periódica o la cita maestra de una serie periódica. Sin embargo, no se puede mostrar una instancia de la serie porque no se puede acceder a las propiedades (incluido el identificador de elemento) de las instancias de una serie periódica.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica una cita existente, se abre un panel en blanco en el equipo o dispositivo cliente y no se devuelve ningún mensaje de error.

Nota: Este método no se admite en Outlook en iOS ni en Android.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.9 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Muestra un mensaje existente.

El displayMessageForm método abre un mensaje existente en una nueva ventana del escritorio.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica un mensaje existente, no se mostrará ningún mensaje en el equipo cliente y no se devolverá ningún mensaje de error.

displayMessageForm(itemId: string): void;

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

• Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

• No use displayMessageForm con un itemId que represente una cita. Use el método displayAppointmentForm para mostrar una cita existente y displayNewAppointmentForm para mostrar un formulario para crear una cita nueva.

Ejemplos

// 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);

Muestra un mensaje existente.

El método displayMessageFormAsync abre un mensaje existente en una nueva ventana del escritorio o en un cuadro de diálogo en los dispositivos móviles.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica un mensaje existente, no se mostrará ningún mensaje en el equipo cliente y no se devolverá ningún mensaje de error.

No use el displayMessageForm método o displayMessageFormAsync con un itemId que represente una cita. Use el displayAppointmentForm método o displayAppointmentFormAsync para mostrar una cita existente o displayNewAppointmentFormdisplayNewAppointmentFormAsync para mostrar un formulario para crear una cita.

Nota: Este método no se admite en Outlook en iOS ni en Android.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.9 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// 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));
});

Muestra un mensaje existente.

El método displayMessageFormAsync abre un mensaje existente en una nueva ventana del escritorio o en un cuadro de diálogo en los dispositivos móviles.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica un mensaje existente, no se mostrará ningún mensaje en el equipo cliente y no se devolverá ningún mensaje de error.

No use el displayMessageForm método o displayMessageFormAsync con un itemId que represente una cita. Use el displayAppointmentForm método o displayAppointmentFormAsync para mostrar una cita existente o displayNewAppointmentFormdisplayNewAppointmentFormAsync para mostrar un formulario para crear una cita.

Nota: Este método no se admite en Outlook en iOS ni en Android.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.9 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Muestra un formulario para crear una cita de calendario.

El método displayNewAppointmentForm abre un formulario que permite al usuario crear una nueva cita o reunión. Si se especifican parámetros, los campos de formulario de cita se rellenan automáticamente con el contenido de los parámetros.

En Outlook en la Web y nueva Outlook en Windows, este método siempre muestra un formulario con un campo de asistentes. Si no especifica ningún asistente como argumentos de entrada, el método muestra un formulario con un botón Guardar . Si ha especificado asistentes, el formulario incluirá a los asistentes y un botón Enviar.

En Outlook en Windows (clásico) y en Mac, si especifica asistentes o recursos en el requiredAttendeesparámetro , optionalAttendeeso resources , este método muestra un formulario de reunión con un botón Enviar . Si no se especifica ningún destinatario, este método muestra un formulario de cita con un botón Guardar y cerrar.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

displayNewAppointmentForm(parameters: AppointmentForm): void;

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

Importante: Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Ejemplos

// 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"],
  optionalAttendees: ["sam@contoso.com"],
  start: start,
  end: end,
  location: "Home",
  subject: "meeting",
  resources: ["projector@contoso.com"],
  body: "Hello World!"
});

Muestra un formulario para crear una cita de calendario.

El método displayNewAppointmentFormAsync abre un formulario que permite al usuario crear una nueva cita o reunión. Si se especifican parámetros, los campos de formulario de cita se rellenan automáticamente con el contenido de los parámetros.

En Outlook en la Web y nueva Outlook en Windows, este método siempre muestra un formulario con un campo de asistentes. Si no especifica ningún asistente como argumento de entrada, el método muestra un formulario con un botón Guardar. Si ha especificado asistentes, el formulario incluirá a los asistentes y un botón Enviar.

En Outlook en Windows (clásico) y en Mac, si especifica asistentes o recursos en el requiredAttendeesparámetro , optionalAttendeeso resources , este método muestra un formulario de reunión con un botón Enviar . Si no se especifica ningún destinatario, este método muestra un formulario de cita con un botón Guardar y cerrar.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

Nota: Este método no se admite en Outlook en iOS ni en Android.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.9 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

Ejemplos

// 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"],
    optionalAttendees: ["sam@contoso.com"],
    start: start,
    end: end,
    location: "Home",
    subject: "meeting",
    resources: ["projector@contoso.com"],
    body: "Hello World!"
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

Muestra un formulario para crear una cita de calendario.

El método displayNewAppointmentFormAsync abre un formulario que permite al usuario crear una nueva cita o reunión. Si se especifican parámetros, los campos de formulario de cita se rellenan automáticamente con el contenido de los parámetros.

En Outlook en la Web y nueva Outlook en Windows, este método siempre muestra un formulario con un campo de asistentes. Si no especifica ningún asistente como argumento de entrada, el método muestra un formulario con un botón Guardar. Si ha especificado asistentes, el formulario incluirá a los asistentes y un botón Enviar.

En Outlook en Windows (clásico) y en Mac, si especifica asistentes o recursos en el requiredAttendeesparámetro , optionalAttendeeso resources , este método muestra un formulario de reunión con un botón Enviar . Si no se especifica ningún destinatario, este método muestra un formulario de cita con un botón Guardar y cerrar.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

Nota: Este método no se admite en Outlook en iOS ni en Android.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.9 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

Muestra un formulario para crear un mensaje.

El displayNewMessageForm método abre un formulario que permite al usuario crear un nuevo mensaje. Si se especifican parámetros, los campos del formulario del mensaje se rellenan automáticamente con el contenido de los parámetros.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

displayNewMessageForm(parameters: any): void;

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.6 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

Ejemplos

// 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
    }
  ]
});

Muestra un formulario para crear un mensaje.

El displayNewMessageFormAsync método abre un formulario que permite al usuario crear un nuevo mensaje. Si se especifican parámetros, los campos del formulario del mensaje se rellenan automáticamente con el contenido de los parámetros.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.9 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

Ejemplos

// 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));
  }
);

Muestra un formulario para crear un mensaje.

El displayNewMessageFormAsync método abre un formulario que permite al usuario crear un nuevo mensaje. Si se especifican parámetros, los campos del formulario del mensaje se rellenan automáticamente con el contenido de los parámetros.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.9 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

Obtiene una cadena que contiene un token que se usa para llamar a las API REST o a Exchange Web Services (EWS).

El método getCallbackTokenAsync realiza una llamada asincrónica para obtener un token opaco desde Exchange Server que hospeda el buzón del usuario. La duración del token de devolución de llamada es de 5 minutos.

El token se devuelve como una cadena en la asyncResult.value propiedad .

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.5 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

• Los tokens de identidad de usuario Exchange Online heredados y los tokens de devolución de llamada ya no se admiten y se desactivan en todos los inquilinos de Microsoft 365. Si un complemento de Outlook requiere acceso de usuario delegado o identidad de usuario, se recomienda usar MSAL (Biblioteca de autenticación de Microsoft) y la autenticación de aplicaciones anidadas (NAA). Los tokens de identidad de usuario de Exchange siguen siendo compatibles con Exchange local.

• Los puntos de conexión REST v2.0 y beta de Outlook ahora están en desuso. Sin embargo, los complementos hospedados en AppSource y de publicación privada pueden usar el servicio REST hasta que finalice el soporte extendido para Outlook 2019 el 14 de octubre de 2025. El tráfico de estos complementos se identifica automáticamente para la exención. Esta exención también se aplica a los nuevos complementos desarrollados a partir del 31 de marzo de 2024. Aunque los complementos pueden usar el servicio REST hasta 2025, le recomendamos encarecidamente que migre los complementos para usar Microsoft Graph. Para obtener instrucciones, consulte Comparación de puntos de conexión de LA API REST de Microsoft Graph y Outlook.

• Para determinar si los tokens REST o EWS están disponibles en una organización, llame a Office.context.mailbox.diagnostics.ews.getTokenStatusAsync. El getTokenStatusAsync método está disponible para la versión preliminar en Outlook en la Web y en Windows (nuevo y clásico (versión 2510, compilación 19328.20000 y versiones posteriores)).

• Este método no se admite si carga un complemento en un buzón de correo de Outlook.com o Gmail.

• Este método solo se admite en modo de lectura en Outlook en Android y en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

• Las operaciones de EWS no se admiten en complementos que se ejecutan en Outlook en iOS y en Android. Siempre se devuelve un token REST en los clientes móviles de Outlook, incluso si options.isRest está establecido en false.

• Llamar al getCallbackTokenAsync método en modo de lectura requiere un nivel de permiso mínimo de elemento de lectura.

• Llamar al getCallbackTokenAsync método en modo de redacción requiere que haya guardado el elemento. El saveAsync método requiere un nivel de permiso mínimo de elemento de lectura y escritura.

• Para obtener instrucciones sobre escenarios de delegación o compartidos, consulte el artículo carpetas compartidas y buzón compartido .

Tokens de REST

Cuando se solicita un token REST (options.isRest = true), el token resultante no funcionará para autenticar las llamadas de EWS. El token se limitará en el ámbito al acceso de solo lectura al elemento actual y sus datos adjuntos, a menos que el complemento haya especificado el permiso de buzón de lectura y escritura en su manifiesto. Si se especifica el permiso de buzón de lectura y escritura , el token resultante concederá acceso de lectura y escritura al correo, el calendario y los contactos, incluida la capacidad de enviar correo.

El complemento debe usar la propiedad restUrl para determinar la URL correcta que se va a usar al realizar las llamadas a la API de REST.

Esta API funciona para los siguientes ámbitos.

• Mail.ReadWrite

• Mail.Send

• Calendars.ReadWrite

• Contacts.ReadWrite

Tokens EWS

Cuando se solicita un token de EWS (options.isRest = false), el token resultante no funcionará para autenticar las llamadas a la API REST. El token estará limitado en su ámbito para el acceso al elemento actual.

El complemento debe usar la propiedad ewsUrl para determinar la URL correcta que se va a usar al realizar las llamadas a EWS.

Puede pasar el token y un identificador de datos adjuntos o un identificador de elemento a un sistema externo. Ese sistema usa el token como token de autorización de portador para llamar a la operación GetAttachment de Servicios web de Exchange (EWS) o a la operación GetItem para devolver datos adjuntos o elementos. Por ejemplo, puede crear un servicio remoto para obtener datos adjuntos del elemento seleccionado.

Errores:

Si se produce un error en la llamada, use la propiedad asyncResult.diagnostics para ver detalles sobre el error.

• GenericTokenError: An internal error has occurred.- En Exchange Online entornos, este error se produce cuando el token no se puede recuperar porque los tokens de Exchange heredados para complementos de Outlook están desactivados. Se recomienda usar NAA como solución de inicio de sesión único para el complemento.

• 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.- En Exchange Online entornos, este error se produce cuando el token no se puede recuperar porque los tokens de Exchange heredados para complementos de Outlook están desactivados. Se recomienda usar NAA como solución de inicio de sesión único para el complemento.

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

Obtiene una cadena que contiene un token usado para obtener datos adjuntos o un elemento de Exchange Server.

El método getCallbackTokenAsync realiza una llamada asincrónica para obtener un token opaco desde Exchange Server que hospeda el buzón del usuario. La duración del token de devolución de llamada es de 5 minutos.

El token se devuelve como una cadena en la asyncResult.value propiedad .

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: todos admiten el modo de lectura; Buzón 1.3 introducido Compose compatibilidad con el modo ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

• Los tokens de identidad de usuario Exchange Online heredados y los tokens de devolución de llamada ya no se admiten y se desactivan en todos los inquilinos de Microsoft 365. Si un complemento de Outlook requiere acceso de usuario delegado o identidad de usuario, se recomienda usar MSAL (Biblioteca de autenticación de Microsoft) y la autenticación de aplicaciones anidadas (NAA). Los tokens de identidad de usuario de Exchange siguen siendo compatibles con Exchange local.

• Puede pasar el token y un identificador de datos adjuntos o un identificador de elemento a un sistema externo. Ese sistema usa el token como token de autorización de portador para llamar a la operación GetAttachment o GetItem de Exchange Web Services (EWS) para devolver datos adjuntos o elementos. Por ejemplo, puede crear un servicio remoto para obtener datos adjuntos del elemento seleccionado.

• Para determinar si los tokens REST o EWS están disponibles en una organización, llame a Office.context.mailbox.diagnostics.ews.getTokenStatusAsync. El getTokenStatusAsync método está disponible para la versión preliminar en Outlook en la Web y en Windows (nuevo y clásico (versión 2510, compilación 19328.20000 y versiones posteriores)).

• Llamar al getCallbackTokenAsync método en modo de lectura requiere un nivel de permiso mínimo de elemento de lectura.

• Llamar al getCallbackTokenAsync método en modo de redacción requiere que haya guardado el elemento. El saveAsync método requiere un nivel de permiso mínimo de elemento de lectura y escritura.

• Este método no se admite en Outlook en Android o en iOS. Las operaciones de EWS no se admiten en complementos que se ejecutan en Outlook en clientes móviles. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

• Este método no se admite si carga un complemento en un buzón de correo de Outlook.com o Gmail.

• Para obtener instrucciones sobre escenarios de delegación o compartidos, consulte el artículo carpetas compartidas y buzón compartido .

Errores:

Si se produce un error en la llamada, use la propiedad asyncResult.diagnostics para ver detalles sobre el error.

• GenericTokenError: An internal error has occurred.- En Exchange Online entornos, este error se produce cuando el token no se puede recuperar porque los tokens de Exchange heredados para complementos de Outlook están desactivados. Se recomienda usar NAA como solución de inicio de sesión único para el complemento.

• 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.- En Exchange Online entornos, este error se produce cuando el token no se puede recuperar porque los tokens de Exchange heredados para complementos de Outlook están desactivados. Se recomienda usar NAA como solución de inicio de sesión único para el complemento.

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

Ejemplos

// 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);
});

Devuelve true si Microsoft Intune administra el buzón actual.

getIsIdentityManaged(): boolean;

Devoluciones

True si Microsoft Intune administra el buzón actual.

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose, Lectura

Importante: Este método solo se admite en Outlook en Android y en iOS a partir de la versión 4.2443.0. Para obtener más información sobre las API admitidas en Outlook en dispositivos móviles, consulte API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Errores:

• MAMServiceNotAvailable : el cliente no puede capturar la directiva de administración de aplicaciones móviles (MAM).

Ejemplos

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

Devuelve true si la directiva de administración de aplicaciones móviles (MAM) Intune de una organización permite a un complemento acceder a los datos desde la ubicación especificada.

getIsOpenFromLocationAllowed(openLocation: MailboxEnums.OpenLocation): boolean;

Parámetros

Devoluciones

True si la directiva mam de Intune de una organización permite a un complemento acceder a los datos desde la ubicación especificada.

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose, Lectura

Importante: Este método solo se admite en Outlook en Android y en iOS a partir de la versión 4.2443.0. Para obtener más información sobre las API admitidas en Outlook en dispositivos móviles, consulte API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Errores:

• InvalidOpenLocationInput : el valor de la ubicación especificada no es válido.

• MAMServiceNotAvailable : el cliente no puede capturar la directiva MAM.

Ejemplos

// 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.");
}

Devuelve true si la directiva de administración de aplicaciones móviles (MAM) Intune de una organización permite a un complemento guardar datos en la ubicación especificada.

getIsSaveToLocationAllowed(saveLocation: MailboxEnums.SaveLocation): boolean;

Parámetros

Devoluciones

True si la directiva mam de Intune de una organización permite a un complemento guardar datos en la ubicación especificada.

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose, Lectura

Importante: Este método solo se admite en Outlook en Android y en iOS a partir de la versión 4.2443.0. Para obtener más información sobre las API admitidas en Outlook en dispositivos móviles, consulte API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Errores:

• InvalidSaveLocationInput : el valor de la ubicación especificada no es válido.

• MAMServiceNotAvailable : el cliente no puede capturar la directiva MAM.

Ejemplos

// 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.");
}

Obtiene los mensajes seleccionados actualmente en los que un complemento puede activar y realizar operaciones. Un complemento puede activarse en un máximo de 100 mensajes a la vez. Para obtener más información sobre la selección múltiple de elementos, vea Activar el complemento de Outlook en varios mensajes.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.13 ]

Nivel mínimo de permiso: buzón de lectura y escritura

Modo de Outlook aplicable: Compose, Lectura

Importante: Este método solo se aplica a los mensajes.

Obtiene los mensajes seleccionados actualmente en los que un complemento puede activar y realizar operaciones. Un complemento puede activarse en un máximo de 100 mensajes a la vez. Para obtener más información sobre la selección múltiple de elementos, vea Activar el complemento de Outlook en varios mensajes.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.13 ]

Nivel mínimo de permiso: buzón de lectura y escritura

Modo de Outlook aplicable: Compose, Lectura

Importante: Este método solo se aplica a los mensajes.

Ejemplos

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

Obtiene un token que identifica al usuario y al complemento de Office.

El token se devuelve como una cadena en la asyncResult.value propiedad .

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

Parámetros

Devoluciones

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

• Los tokens de identidad de usuario Exchange Online heredados y los tokens de devolución de llamada ya no se admiten y se desactivan en todos los inquilinos de Microsoft 365. Si un complemento de Outlook requiere acceso de usuario delegado o identidad de usuario, se recomienda usar MSAL (Biblioteca de autenticación de Microsoft) y la autenticación de aplicaciones anidadas (NAA). Los tokens de identidad de usuario de Exchange siguen siendo compatibles con Exchange local.

• El getUserIdentityTokenAsync método devuelve un token que puede usar para identificar y autenticar el complemento y el usuario con un sistema externo.

• Este método no se admite si carga un complemento en un buzón de correo de Outlook.com o Gmail.

Errores:

Si se produce un error en la llamada, use la propiedad asyncResult.diagnostics para ver detalles sobre el error.

• GenericTokenError: An internal error has occurred.- En Exchange Online entornos, este error se produce cuando el token no se puede recuperar porque los tokens de Exchange heredados para complementos de Outlook están desactivados. Se recomienda usar NAA como solución de inicio de sesión único para el complemento.

• 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.- En Exchange Online entornos, este error se produce cuando el token no se puede recuperar porque los tokens de Exchange heredados para complementos de Outlook están desactivados. Se recomienda usar NAA como solución de inicio de sesión único para el complemento.

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

Ejemplos

// 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);
});

Carga un único elemento de correo por su identificador de Exchange Web Services (EWS). A continuación, obtiene un objeto que proporciona las propiedades y los métodos del elemento cargado.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.15 ]

Nivel mínimo de permiso: buzón de lectura y escritura

Modo de Outlook aplicable: Compose, Lectura

Importante:

• Este método solo se aplica a los mensajes.

• Al implementar la característica de selección múltiple de elementos, llame Office.context.mailbox.getSelectedItemsAsync a para obtener los identificadores de elemento de cada elemento seleccionado, de modo que se puedan cargar de uno en uno.

• Antes de implementar el loadItemByIdAsync método con la característica de selección múltiple del elemento, determine si ya puede acceder a las propiedades necesarias del elemento seleccionado mediante la Office.context.mailbox.getSelectedItemsAsync llamada. Si puede, no es necesario llamar loadItemByIdAsynca .

• Solo se puede cargar un elemento de correo a la vez. Al implementar loadItemByIdAsync, debe llamar a unloadAsync después de procesar el elemento. Esto debe hacerse antes de llamar a loadItemByIdAsync en otro elemento.

• Solo loadItemByIdAsync se puede llamar al método en los mensajes del mismo buzón.

Ejemplos

// 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((resolve) => {
    Office.context.mailbox.loadItemByIdAsync(itemId, (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(result.error.message);
        return;
      }

      const loadedItem = result.value;
      const sender = loadedItem.from.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);
          return;
        }

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

Carga un único elemento de correo por su identificador de Exchange Web Services (EWS). A continuación, obtiene un objeto que proporciona las propiedades y los métodos del elemento cargado.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.15 ]

Nivel mínimo de permiso: buzón de lectura y escritura

Modo de Outlook aplicable: Compose, Lectura

Importante:

• Este método solo se aplica a los mensajes.

• Al implementar la característica de selección múltiple de elementos, llame Office.context.mailbox.getSelectedItemsAsync a para obtener los identificadores de elemento de cada elemento seleccionado, de modo que se puedan cargar de uno en uno.

• Antes de implementar el loadItemByIdAsync método con la característica de selección múltiple del elemento, determine si ya puede acceder a las propiedades necesarias del elemento seleccionado mediante la Office.context.mailbox.getSelectedItemsAsync llamada. Si puede, no es necesario llamar loadItemByIdAsynca .

• Solo se puede cargar un elemento de correo a la vez. Al implementar loadItemByIdAsync, debe llamar a unloadAsync después de procesar el elemento. Esto debe hacerse antes de llamar a loadItemByIdAsync en otro elemento.

• Solo loadItemByIdAsync se puede llamar al método en los mensajes del mismo buzón.

Realiza una solicitud asincrónica a un servicio de Exchange Web Services (EWS) en el servidor exchange que hospeda el buzón del usuario.

El método makeEwsRequestAsync envía una solicitud de EWS en nombre del complemento a Exchange.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: buzón de lectura y escritura

Modo de Outlook aplicable: Compose o lectura

Importante:

• Los tokens de identidad de usuario Exchange Online heredados y los tokens de devolución de llamada ya no se admiten y se desactivan en todos los inquilinos de Microsoft 365. Si un complemento de Outlook requiere acceso de usuario delegado o identidad de usuario, se recomienda usar MSAL (Biblioteca de autenticación de Microsoft) y la autenticación de aplicaciones anidadas (NAA). Los tokens de identidad de usuario de Exchange siguen siendo compatibles con Exchange local.

• Para habilitar el makeEwsRequestAsync método para realizar solicitudes de EWS, el administrador del servidor debe establecer en OAuthAuthenticationtrue en el directorio EWS del servidor de acceso de cliente .

• El complemento debe tener el permiso de buzón de lectura y escritura para usar el makeEwsRequestAsync método . Para obtener información sobre cómo usar el permiso de buzón de lectura y escritura y las operaciones de EWS a las que puede llamar con el makeEwsRequestAsync método , vea Especificar permisos para el acceso del complemento de correo al buzón del usuario.

• Si el complemento necesita tener acceso a elementos asociados a la carpeta o su solicitud XML debe especificar la codificación UTF-8 (\<?xml version="1.0" encoding="utf-8"?\>), debe usar Microsoft Graph o las API REST para acceder al buzón del usuario en su lugar.

• Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

• Este método no se admite cuando el complemento se carga en un buzón de Gmail.

• Cuando se usa el makeEwsRequestAsync método en complementos que se ejecutan en versiones de Outlook anteriores a la versión 15.0.4535.1004, debe establecer el valor de codificación en ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>). Para determinar la versión de un cliente de Outlook, use la mailbox.diagnostics.hostVersion propiedad . No es necesario establecer el valor de codificación cuando el complemento se ejecuta en Outlook en la Web y nueva Outlook en Windows. Para determinar el cliente de Outlook en el que se ejecuta el complemento, use la mailbox.diagnostics.hostName propiedad .

Ejemplos

// 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);
});

Elimina el controlador de eventos de un tpo de evento admitido. Nota: Los eventos solo están disponibles con la implementación del panel de tareas.

Para ver los eventos admitidos, consulte la sección Eventos del modelo de objetos de buzón.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.5 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Elimina el controlador de eventos de un tpo de evento admitido. Nota: Los eventos solo están disponibles con la implementación del panel de tareas.

Para ver los eventos admitidos, consulte la sección Eventos del modelo de objetos de buzón.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: Buzón 1.5 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

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.");
});