Edit

Share via

Office.Recipients interface

  • Reference
Package:
outlook

Represents recipients of an item. Compose mode only.

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Compose

Methods

addAsync(recipients, options, callback)

Adds a recipient list to the existing recipients for an appointment or message.
addAsync(recipients, callback)

Adds a recipient list to the existing recipients for an appointment or message.
getAsync(options, callback)

Gets a recipient list for an appointment or message.
getAsync(callback)

Gets a recipient list for an appointment or message.
setAsync(recipients, options, callback)

Sets a recipient list for an appointment or message.

The setAsync method overwrites the current recipient list.
setAsync(recipients, callback)

Sets a recipient list for an appointment or message.

The setAsync method overwrites the current recipient list.

Method Details

addAsync(recipients, options, callback)

Adds a recipient list to the existing recipients for an appointment or message.

addAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

recipients

Array<string | Office.EmailUser | Office.EmailAddressDetails>

The recipients to add to the recipients list. The array of recipients can contain strings of SMTP email addresses, EmailUser objects, or EmailAddressDetails objects.

options
Office.AsyncContextOptions

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

callback

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

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If adding the recipients fails, the asyncResult.error property will contain an error code.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Important: With the addAsync method, you can add a maximum of 100 recipients to a mail item in Outlook on the web, on Windows (new and classic), on Mac (classic UI), on Android, and on iOS. However, take note of the following:

  • In Outlook on the web, on Windows (new and classic), and on Mac (classic UI), you can have a maximum of 500 recipients in a target field. If you need to add more than 100 recipients to a mail item, you can call addAsync repeatedly, but be mindful of the recipient limit of the field.

  • In Outlook on Android and on iOS, the addAsync method isn't supported in Message Compose mode. Only the Appointment Organizer mode is supported. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

There's no recipient limit if you call addAsync in Outlook on Mac (new UI).

Errors:

  • NumberOfRecipientsExceeded: The number of recipients exceeded 100 entries.

Examples

// The following example creates an array of EmailUser objects
// and adds them to the To recipients of the message.
const newRecipients = [
    {
        "displayName": "Allie Bellew",
        "emailAddress": "allieb@contoso.com"
    },
    {
        "displayName": "Alex Darrow",
        "emailAddress": "alexd@contoso.com"
    }
];

Office.context.mailbox.item.to.addAsync(newRecipients, function(result) {
    if (result.error) {
        console.log(result.error);
    } else {
        console.log("Recipients added");
    }
});

addAsync(recipients, callback)

Adds a recipient list to the existing recipients for an appointment or message.

addAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

recipients

Array<string | Office.EmailUser | Office.EmailAddressDetails>

The recipients to add to the recipients list. The array of recipients can contain strings of SMTP email addresses, EmailUser objects, or EmailAddressDetails objects.

callback

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

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If adding the recipients fails, the asyncResult.error property will contain an error code.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Important: With the addAsync method, you can add a maximum of 100 recipients to a mail item in Outlook on the web, on Windows (new and classic), on Mac (classic UI), on Android, and on iOS. However, take note of the following:

  • In Outlook on the web, on Windows (new and classic), and on Mac (classic UI), you can have a maximum of 500 recipients in a target field. If you need to add more than 100 recipients to a mail item, you can call addAsync repeatedly, but be mindful of the recipient limit of the field.

  • In Outlook on Android and on iOS, the addAsync method isn't supported in Message Compose mode. Only the Appointment Organizer mode is supported. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

There's no recipient limit if you call addAsync in Outlook on Mac (new UI).

Errors:

  • NumberOfRecipientsExceeded: The number of recipients exceeded 100 entries.

getAsync(options, callback)

Gets a recipient list for an appointment or message.

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

Parameters

options
Office.AsyncContextOptions

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

callback

(asyncResult: Office.AsyncResult<Office.EmailAddressDetails[]>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, of type Office.AsyncResult. The asyncResult.value property of the result is an array of EmailAddressDetails objects.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Compose

Important:

The maximum number of recipients returned by this method varies per Outlook client.

  • Windows (new and classic), web browser, Mac (classic UI): 500 recipients

  • Android, iOS: 100 recipients

  • Mac (new UI): No limit

In classic Outlook on Windows, the appointment organizer is included in the object returned by the getAsync method when you create a new appointment or edit an existing one. In Outlook on the web and new Outlook on Windows, the organizer is only included in the returned object when you edit an existing appointment.

The getAsync method only returns recipients resolved by the Outlook client. A resolved recipient has the following characteristics.

  • If the recipient has a saved entry in the sender's address book, Outlook resolves the email address to the recipient's saved display name.

  • A Teams meeting status icon appears before the recipient's name or email address.

  • A semicolon appears after the recipient's name or email address.

  • The recipient's name or email address is underlined or enclosed in a box.

To resolve an email address once it's added to a mail item, the sender must use the Tab key or select a suggested contact or email address from the auto-complete list.

In Outlook on the web and on Windows (new and classic), if a user creates a new message by activating a contact's email address link from their contact or profile card, your add-in's Recipients.getAsync call returns the contact's email address in the displayName property of the associated EmailAddressDetails object instead of the contact's saved name. For more details, see related GitHub issue.

While composing a mail item, when you switch to a sender account that's on a different domain than that of the previously selected sender account, the value of the recipientType property for existing recipients isn't updated and will still be based on the domain of the previously selected account. To get the correct recipient types after switching accounts, you must first remove the existing recipients, then add them back to the mail item.

getAsync(callback)

Gets a recipient list for an appointment or message.

getAsync(callback: (asyncResult: Office.AsyncResult<EmailAddressDetails[]>) => void): void;

Parameters

callback

(asyncResult: Office.AsyncResult<Office.EmailAddressDetails[]>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, of type Office.AsyncResult. The asyncResult.value property of the result is an array of EmailAddressDetails objects.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Compose

Important:

The maximum number of recipients returned by this method varies per Outlook client.

  • Windows (new and classic), web browser, Mac (classic UI): 500 recipients

  • Android, iOS: 100 recipients

  • Mac (new UI): No limit

The getAsync method only returns recipients resolved by the Outlook client. A resolved recipient has the following characteristics.

  • If the recipient has a saved entry in the sender's address book, Outlook resolves the email address to the recipient's saved display name.

  • A Teams meeting status icon appears before the recipient's name or email address.

  • A semicolon appears after the recipient's name or email address.

  • The recipient's name or email address is underlined or enclosed in a box.

To resolve an email address once it's added to a mail item, the sender must use the Tab key or select a suggested contact or email address from the auto-complete list.

In Outlook on the web and on Windows (new and classic), if a user creates a new message by activating a contact's email address link from their contact or profile card, your add-in's Recipients.getAsync call returns the contact's email address in the displayName property of the associated EmailAddressDetails object instead of the contact's saved name. For more details, see related GitHub issue.

While composing a mail item, when you switch to a sender account that's on a different domain than that of the previously selected sender account, the value of the recipientType property for existing recipients isn't updated and will still be based on the domain of the previously selected account. To get the correct recipient types after switching accounts, you must first remove the existing recipients, then add them back to the mail item.

Examples

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

Office.context.mailbox.item.bcc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgBcc = asyncResult.value;
    console.log("Message being blind-copied to:");
    for (let i = 0; i < msgBcc.length; i++) {
      console.log(msgBcc[i].displayName + " (" + msgBcc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.cc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgCc = asyncResult.value;
    console.log("Message being copied to:");
    for (let i = 0; i < msgCc.length; i++) {
      console.log(msgCc[i].displayName + " (" + msgCc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

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

...

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

...

Office.context.mailbox.item.to.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgTo = asyncResult.value;
    console.log("Message being sent to:");
    for (let i = 0; i < msgTo.length; i++) {
      console.log(msgTo[i].displayName + " (" + msgTo[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

setAsync(recipients, options, callback)

Sets a recipient list for an appointment or message.

The setAsync method overwrites the current recipient list.

setAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

recipients

Array<string | Office.EmailUser | Office.EmailAddressDetails>

The recipients to add to the recipients list. The array of recipients can contain strings of SMTP email addresses, EmailUser objects, or EmailAddressDetails objects.

options
Office.AsyncContextOptions

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

callback

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

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If setting the recipients fails the asyncResult.error property will contain a code that indicates any error that occurred while adding the data.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Important: With the setAsync method, you can set a maximum of 100 recipients in Outlook on the web, on Windows (new and classic), on Mac (classic UI), on Android, and on iOS. However, take note of the following:

  • In Outlook on the web, on Windows (new and classic), and on Mac (classic UI), you can have a maximum of 500 recipients in a target field. If you need to set more than 100 recipients, you can call setAsync repeatedly, but be mindful of the recipient limit of the field.

  • In Outlook on Android and on iOS, the setAsync method isn't supported in the Message Compose mode. Only the Appointment Organizer mode is supported. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

There's no recipient limit if you call setAsync in Outlook on Mac (new UI).

Errors:

  • NumberOfRecipientsExceeded: The number of recipients exceeded 100 entries.

setAsync(recipients, callback)

Sets a recipient list for an appointment or message.

The setAsync method overwrites the current recipient list.

setAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, callback: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

recipients

Array<string | Office.EmailUser | Office.EmailAddressDetails>

The recipients to add to the recipients list. The array of recipients can contain strings of SMTP email addresses, EmailUser objects, or EmailAddressDetails objects.

callback

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

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If setting the recipients fails the asyncResult.error property will contain a code that indicates any error that occurred while adding the data.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Important: With the setAsync method, you can set a maximum of 100 recipients in Outlook on the web, on Windows (new and classic), on Mac (classic UI), on Android, and on iOS. However, take note of the following:

  • In Outlook on the web, on Windows (new and classic), and on Mac (classic UI), you can have a maximum of 500 recipients in a target field. If you need to set more than 100 recipients, you can call setAsync repeatedly, but be mindful of the recipient limit of the field.

  • In Outlook on Android and on iOS, the setAsync method isn't supported in the Message Compose mode. Only the Appointment Organizer mode is supported. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

There's no recipient limit if you call setAsync in Outlook on Mac (new UI).

Errors:

  • NumberOfRecipientsExceeded: The number of recipients exceeded 100 entries.

Examples

// The following example creates an array of EmailUser objects and
// replaces the CC recipients of the message with the array.
const newRecipients = [
    {
        "displayName": "Allie Bellew",
        "emailAddress": "allieb@contoso.com"
    },
    {
        "displayName": "Alex Darrow",
        "emailAddress": "alexd@contoso.com"
    }
];

Office.context.mailbox.item.cc.setAsync(newRecipients, function(result) {
    if (result.error) {
        console.log(result.error);
    } else {
        console.log("Recipients overwritten");
    }
});

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

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

...

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

...

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

...

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

...

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