Obtener, establecer o agregar destinatarios al redactar una cita o mensaje en Outlook

La API de JavaScript de Office proporciona métodos asincrónicos (Recipients.getAsync, Recipients.setAsync o Recipients.addAsync) para obtener, establecer o agregar destinatarios respectivamente a un formulario de redacción de una cita o mensaje. Estos métodos asincrónicos solo están disponibles para crear complementos. Para usar estos métodos, asegúrese de que ha configurado el manifiesto del complemento correctamente para que Outlook active el complemento en formularios de redacción, como se describe en Crear complementos de Outlook para formularios de redacción.

Algunas de las propiedades que representan destinatarios de una cita o mensaje están disponibles para el acceso de lectura tanto en formularios de redacción como en formularios de lectura. Entre estas propiedades se incluyen optionalAttendees y requiredAttendees para citas y cc y to para mensajes.

En los formularios de lectura puede obtener acceso a la propiedad directamente desde el objeto primario, por ejemplo:

Office.context.mailbox.item.cc;

Pero en un formulario de redacción, dado que tanto el usuario como el complemento pueden insertar o cambiar un destinatario al mismo tiempo, debe usar el método getAsync asincrónico para obtener estas propiedades, como en el ejemplo siguiente.

Office.context.mailbox.item.cc.getAsync(callback);

Estas propiedades están disponibles para el acceso de escritura solo en formularios de redacción y no en formularios de lectura.

Al igual que con la mayoría de los métodos asincrónicos de la API de JavaScript para Office, getAsync, setAsyncy addAsync toman parámetros de entrada opcionales. Para obtener más información sobre cómo especificar estos parámetros de entrada opcionales, vea "Pasar parámetros opcionales a métodos asincrónicos" en Programación asincrónica en complementos de Office.

Obtener los destinatarios

En esta sección se muestra un ejemplo de código que obtiene los destinatarios de la cita o mensaje que se redacte y muestra sus direcciones de correo electrónico.

En la API de JavaScript de Office, dado que las propiedades que representan a los destinatarios de una cita (optionalAttendees y requiredAttendees) son diferentes de las de un mensaje (bcc, ccy to), primero debe usar la propiedad item.itemType para identificar si el elemento que se va a componer es una cita o un mensaje. En el modo de redacción, todas estas propiedades de citas y mensajes son objetos Recipients , por lo que puede llamar al método asincrónico, Recipients.getAsync, para obtener los destinatarios correspondientes.

Para usar getAsync, proporcione una función de devolución de llamada para comprobar el estado, los resultados y cualquier error devuelto por la llamada asincrónica getAsync . La función de devolución de llamada devuelve un parámetro de salida asyncResult . Use sus status propiedades y error para comprobar el estado y los mensajes de error de la llamada asincrónica y su value propiedad para obtener los destinatarios reales. Los destinatarios se representan como una matriz de objetos EmailAddressDetails. También puede proporcionar información adicional a la función de devolución de llamada mediante el parámetro opcional asyncContext en la getAsync llamada.

Tenga en cuenta que, dado que el getAsync método es asincrónico, si hay acciones posteriores que dependen de obtener correctamente los destinatarios, debe organizar el código para iniciar dichas acciones solo en la función de devolución de llamada correspondiente cuando la llamada asincrónica se haya completado correctamente.

Importante

El getAsync método solo devuelve destinatarios resueltos por el cliente de Outlook. Un destinatario resuelto tiene las siguientes características.

• Si el destinatario tiene una entrada guardada en la libreta de direcciones del remitente, Outlook resuelve la dirección de correo electrónico en el nombre para mostrar guardado del destinatario.
• Aparece un icono de estado de reunión de Teams antes del nombre o la dirección de correo electrónico del destinatario.
• Aparece un punto y coma después del nombre o la dirección de correo electrónico del destinatario.
• El nombre o la dirección de correo electrónico del destinatario están subrayados o incluidos en un cuadro.

Para resolver una dirección de correo electrónico una vez agregada a un elemento de correo, el remitente debe usar la tecla Tab o seleccionar una dirección de contacto o correo electrónico sugerida de la lista de autocompletar.

En Outlook en la Web y en Windows (nuevo y clásico), si un usuario crea un nuevo mensaje seleccionando el vínculo de dirección de correo electrónico de un contacto desde una tarjeta de contacto o perfil, primero debe resolver la dirección de correo electrónico para que se pueda incluir en los resultados de la getAsync llamada.

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        getAllRecipients();
    }
});

// Gets the email addresses of all the recipients of the item being composed.
function getAllRecipients() {
    let toRecipients, ccRecipients, bccRecipients;

    // Verify if the mail item is an appointment or message.
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        toRecipients = item.requiredAttendees;
        ccRecipients = item.optionalAttendees;
    }
    else {
        toRecipients = item.to;
        ccRecipients = item.cc;
        bccRecipients = item.bcc;
    }

    // Get the recipients from the To or Required field of the item being composed.
    toRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients or attendees.
        write(`Recipients in the To or Required field: ${displayAddresses(asyncResult.value)}`);
    });

    // Get the recipients from the Cc or Optional field of the item being composed.
    ccRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients or attendees.
        write(`Recipients in the Cc or Optional field: ${displayAddresses(asyncResult.value)}`);
    });

    // Get the recipients from the Bcc field of the message being composed, if applicable.
    if (bccRecipients.length > 0) {
        bccRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients.
        write(`Recipients in the Bcc field: ${displayAddresses(asyncResult.value)}`);
        });
    } else {
        write("Recipients in the Bcc field: None");
    }
}

// Displays the email address of each recipient.
function displayAddresses (recipients) {
    for (let i = 0; i < recipients.length; i++) {
        write(recipients[i].emailAddress);
    }
}

// Writes to a div with id="message" on the page.
function write(message) {
    document.getElementById("message").innerText += message;
}

Definir los destinatarios

En esta sección se muestra un ejemplo de código que define los destinatarios de la cita o mensaje que el usuario está redactando. Al definir los destinatarios, se sobrescribirán los destinatarios existentes. En este ejemplo se comprueba primero si el elemento de correo es una cita o mensaje, de modo que puede llamar al método asincrónico, Recipients.setAsync, en las propiedades adecuadas que representan a los destinatarios de la cita o mensaje.

Al llamar a setAsync, proporcione una matriz como argumento de entrada para el recipients parámetro, en uno de los siguientes formatos.

• Una matriz de cadenas que son direcciones SMTP.
• Una matriz de diccionarios, cada uno de los cuales contiene un nombre para mostrar y una dirección de correo electrónico, tal y como se muestra en el ejemplo de código siguiente.
• Matriz de EmailAddressDetails objetos, similar a la devuelta por el getAsync método .

Opcionalmente, puede proporcionar una función de devolución de llamada como argumento de entrada al setAsync método para asegurarse de que cualquier código que dependa de la configuración correcta de los destinatarios solo se ejecutaría cuando eso ocurra. Si implementa una función de devolución de llamada, use las status propiedades y error del asyncResult parámetro de salida para comprobar el estado y los mensajes de error de la llamada asincrónica. Para proporcionar información adicional a la función de devolución de llamada, use el parámetro opcional asyncContext en la setAsync llamada.

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        setRecipients();
    }
});

// Sets the recipients of the item being composed.
function setRecipients() {
    let toRecipients, ccRecipients, bccRecipients;

    // Verify if the mail item is an appointment or message.
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        toRecipients = item.requiredAttendees;
        ccRecipients = item.optionalAttendees;
    }
    else {
        toRecipients = item.to;
        ccRecipients = item.cc;
        bccRecipients = item.bcc;
    }

    // Set the recipients in the To or Required field of the item being composed.
    toRecipients.setAsync(
        [{
            "displayName": "Graham Durkin", 
            "emailAddress": "graham@contoso.com"
         },
         {
            "displayName": "Donnie Weinberg",
            "emailAddress": "donnie@contoso.com"
         }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the recipients in the To or Required field.");
            // Run additional operations appropriate to your scenario.
    });

    // Set the recipients in the Cc or Optional field of the item being composed.
    ccRecipients.setAsync(
        [{
            "displayName": "Perry Horning", 
            "emailAddress": "perry@contoso.com"
         },
         {
            "displayName": "Guy Montenegro",
            "emailAddress": "guy@contoso.com"
         }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the recipients in the Cc or Optional field.");
            // Run additional operations appropriate to your scenario.
    });

    // Set the recipients in the Bcc field of the message being composed.
    if (bccRecipients) {
        bccRecipients.setAsync(
            [{
                "displayName": "Lewis Cate", 
                "emailAddress": "lewis@contoso.com"
            },
            {
                "displayName": "Francisco Stitt",
                "emailAddress": "francisco@contoso.com"
            }],
            (asyncResult) => {
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    console.log(asyncResult.error.message);
                    return;
                }
    
                console.log("Successfully set the recipients in the Bcc field.");
                // Run additional operations appropriate to your scenario.
        });
    }
}

Agregar destinatarios

Si no desea sobrescribir ningún destinatario existente en una cita o mensaje, en lugar de usar Recipients.setAsync, use el Recipients.addAsync método asincrónico para anexar destinatarios. addAsync funciona de forma similar setAsync a en que requiere un argumento de recipients entrada. Opcionalmente, puede proporcionar una función de devolución de llamada y cualquier argumento para la devolución de llamada mediante el asyncContext parámetro . A continuación, compruebe el estado, el resultado y cualquier error de la llamada asincrónica addAsync mediante el asyncResult parámetro de salida de la función de devolución de llamada. En el ejemplo siguiente se comprueba si el elemento que se va a componer es una cita y, a continuación, le anexa dos asistentes necesarios.

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        addAttendees();
    }
});

// Adds the specified recipients as required attendees of the appointment.
function addAttendees() {
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        item.requiredAttendees.addAsync(
        [{
            "displayName": "Kristie Jensen",
            "emailAddress": "kristie@contoso.com"
         },
         {
            "displayName": "Pansy Valenzuela",
            "emailAddress": "pansy@contoso.com"
          }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully added the required attendees.");
            // Run additional operations appropriate to your scenario.
        });
    }
}

Vea también

• Crear complementos de Outlook para formularios de redacción
• Programación asincrónica en los complementos de Office
• Obtener o establecer el asunto al redactar una cita o mensaje en Outlook
• Insertar datos en el cuerpo al redactar una cita o mensaje en Outlook
• Obtener o establecer la ubicación al redactar una cita en Outlook
• Obtener o establecer la hora al redactar una cita en Outlook