office.recipients.yml

### YamlMime:TSType
name: Office.Recipients
uid: 'outlook!Office.Recipients:interface'
package: outlook!
fullName: Office.Recipients
summary: Represents recipients of an item. Compose mode only.
remarks: >-
  \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


  **[Minimum permission
  level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!-- -->**:
  **read item**


  **[Applicable Outlook
  mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!-- -->**:
  Compose
isPreview: false
isDeprecated: false
type: interface
methods:
  - name: 'addAsync(recipients, options, callback)'
    uid: 'outlook!Office.Recipients#addAsync:member(1)'
    package: outlook!
    fullName: 'addAsync(recipients, options, callback)'
    summary: Adds a recipient list to the existing recipients for an appointment or message.
    remarks: >-
      \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


      **[Minimum permission
      level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
      -->**: **read/write item**


      **[Applicable Outlook
      mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
      -->**: 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, on Mac (classic UI), on Android, and on iOS. However, take note of the following:


      - In Outlook on the web, on Windows, 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](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis)<!-- -->.


      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


      ```TypeScript

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

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        addAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, options: Office.AsyncContextOptions,
        callback?: (asyncResult: Office.AsyncResult<void>) => void): void;
      parameters:
        - id: recipients
          description: >-
            The recipients to add to the recipients list. The array of recipients can contain strings of SMTP email
            addresses, [EmailUser](xref:outlook!Office.EmailUser:interface) objects, or
            [EmailAddressDetails](xref:outlook!Office.EmailAddressDetails:interface) objects.
          type: >-
            Array&lt;string | <xref uid="outlook!Office.EmailUser:interface" /> | <xref
            uid="outlook!Office.EmailAddressDetails:interface" />&gt;
        - id: options
          description: >-
            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.
          type: '<xref uid="office!Office.AsyncContextOptions:interface" />'
        - id: callback
          description: >-
            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.
          type: '(asyncResult: <xref uid="office!Office.AsyncResult:interface" />&lt;void&gt;) =&gt; void'
      return:
        type: void
        description: ''
  - name: 'addAsync(recipients, callback)'
    uid: 'outlook!Office.Recipients#addAsync:member(2)'
    package: outlook!
    fullName: 'addAsync(recipients, callback)'
    summary: Adds a recipient list to the existing recipients for an appointment or message.
    remarks: >-
      \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


      **[Minimum permission
      level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
      -->**: **read/write item**


      **[Applicable Outlook
      mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
      -->**: 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, on Mac (classic UI), on Android, and on iOS. However, take note of the following:


      - In Outlook on the web, on Windows, 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](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis)<!-- -->.


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


      **Errors**:


      - `NumberOfRecipientsExceeded`<!-- -->: The number of recipients exceeded 100 entries.
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        addAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, callback?: (asyncResult:
        Office.AsyncResult<void>) => void): void;
      parameters:
        - id: recipients
          description: >-
            The recipients to add to the recipients list. The array of recipients can contain strings of SMTP email
            addresses, [EmailUser](xref:outlook!Office.EmailUser:interface) objects, or
            [EmailAddressDetails](xref:outlook!Office.EmailAddressDetails:interface) objects.
          type: >-
            Array&lt;string | <xref uid="outlook!Office.EmailUser:interface" /> | <xref
            uid="outlook!Office.EmailAddressDetails:interface" />&gt;
        - id: callback
          description: >-
            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.
          type: '(asyncResult: <xref uid="office!Office.AsyncResult:interface" />&lt;void&gt;) =&gt; void'
      return:
        type: void
        description: ''
  - name: 'getAsync(options, callback)'
    uid: 'outlook!Office.Recipients#getAsync:member(1)'
    package: outlook!
    fullName: 'getAsync(options, callback)'
    summary: Gets a recipient list for an appointment or message.
    remarks: >-
      \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


      **[Minimum permission
      level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
      -->**: **read item**


      **[Applicable Outlook
      mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
      -->**: Compose


      **Important**:


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


      - Windows, 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, 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](xref:outlook!Office.EmailAddressDetails:interface) object instead of the contact's saved
      name. For more details, see [related GitHub issue](https://github.com/OfficeDev/office-js/issues/2201)<!-- -->.
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        getAsync(options: Office.AsyncContextOptions, callback: (asyncResult:
        Office.AsyncResult<EmailAddressDetails[]>) => void): void;
      parameters:
        - id: options
          description: >-
            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.
          type: '<xref uid="office!Office.AsyncContextOptions:interface" />'
        - id: callback
          description: >-
            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](xref:outlook!Office.EmailAddressDetails:interface) objects.
          type: >-
            (asyncResult: <xref uid="office!Office.AsyncResult:interface" />&lt;<xref
            uid="outlook!Office.EmailAddressDetails:interface" />[]&gt;) =&gt; void
      return:
        type: void
        description: ''
  - name: getAsync(callback)
    uid: 'outlook!Office.Recipients#getAsync:member(2)'
    package: outlook!
    fullName: getAsync(callback)
    summary: Gets a recipient list for an appointment or message.
    remarks: >-
      \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


      **[Minimum permission
      level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
      -->**: **read item**


      **[Applicable Outlook
      mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
      -->**: Compose


      **Important**:


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


      - Windows, 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, 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](xref:outlook!Office.EmailAddressDetails:interface) object instead of the contact's saved
      name. For more details, see [related GitHub issue](https://github.com/OfficeDev/office-js/issues/2201)<!-- -->.


      #### Examples


      ```TypeScript

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

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getAsync(callback: (asyncResult: Office.AsyncResult<EmailAddressDetails[]>) => void): void;'
      parameters:
        - id: callback
          description: >-
            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](xref:outlook!Office.EmailAddressDetails:interface) objects.
          type: >-
            (asyncResult: <xref uid="office!Office.AsyncResult:interface" />&lt;<xref
            uid="outlook!Office.EmailAddressDetails:interface" />[]&gt;) =&gt; void
      return:
        type: void
        description: ''
  - name: 'setAsync(recipients, options, callback)'
    uid: 'outlook!Office.Recipients#setAsync:member(1)'
    package: outlook!
    fullName: 'setAsync(recipients, options, callback)'
    summary: |-
      Sets a recipient list for an appointment or message.

      The `setAsync` method overwrites the current recipient list.
    remarks: >-
      \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


      **[Minimum permission
      level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
      -->**: **read/write item**


      **[Applicable Outlook
      mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
      -->**: Compose


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


      - In Outlook on the web, on Windows, 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](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis)<!-- -->.


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


      **Errors**:


      - `NumberOfRecipientsExceeded`<!-- -->: The number of recipients exceeded 100 entries.
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        setAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, options: Office.AsyncContextOptions,
        callback: (asyncResult: Office.AsyncResult<void>) => void): void;
      parameters:
        - id: recipients
          description: >-
            The recipients to add to the recipients list. The array of recipients can contain strings of SMTP email
            addresses, [EmailUser](xref:outlook!Office.EmailUser:interface) objects, or
            [EmailAddressDetails](xref:outlook!Office.EmailAddressDetails:interface) objects.
          type: >-
            Array&lt;string | <xref uid="outlook!Office.EmailUser:interface" /> | <xref
            uid="outlook!Office.EmailAddressDetails:interface" />&gt;
        - id: options
          description: >-
            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.
          type: '<xref uid="office!Office.AsyncContextOptions:interface" />'
        - id: callback
          description: >-
            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.
          type: '(asyncResult: <xref uid="office!Office.AsyncResult:interface" />&lt;void&gt;) =&gt; void'
      return:
        type: void
        description: ''
  - name: 'setAsync(recipients, callback)'
    uid: 'outlook!Office.Recipients#setAsync:member(2)'
    package: outlook!
    fullName: 'setAsync(recipients, callback)'
    summary: |-
      Sets a recipient list for an appointment or message.

      The `setAsync` method overwrites the current recipient list.
    remarks: >-
      \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


      **[Minimum permission
      level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
      -->**: **read/write item**


      **[Applicable Outlook
      mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
      -->**: Compose


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


      - In Outlook on the web, on Windows, 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](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis)<!-- -->.


      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


      ```TypeScript

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

      ```

      ```TypeScript

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

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        setAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, callback: (asyncResult:
        Office.AsyncResult<void>) => void): void;
      parameters:
        - id: recipients
          description: >-
            The recipients to add to the recipients list. The array of recipients can contain strings of SMTP email
            addresses, [EmailUser](xref:outlook!Office.EmailUser:interface) objects, or
            [EmailAddressDetails](xref:outlook!Office.EmailAddressDetails:interface) objects.
          type: >-
            Array&lt;string | <xref uid="outlook!Office.EmailUser:interface" /> | <xref
            uid="outlook!Office.EmailAddressDetails:interface" />&gt;
        - id: callback
          description: >-
            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.
          type: '(asyncResult: <xref uid="office!Office.AsyncResult:interface" />&lt;void&gt;) =&gt; void'
      return:
        type: void
        description: ''