Office.Recipients interface

Represents recipients of an item. Compose mode only.

[ API set: Mailbox 1.1 ]

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose

Methods

addAsync(recipients, options, callback)

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

The recipients parameter can be an array of one of the following:

Maximum number that can be added:

  • Windows: 100 recipients. Note: Can call API repeatedly but the maximum number of recipients in the target field on the item is 500 recipients.

  • Mac, web browser: 100 recipients

  • Other: No limit

[ API set: Mailbox 1.1 ]

addAsync(recipients, callback)

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

The recipients parameter can be an array of one of the following:

Maximum number that can be added:

  • Windows: 100 recipients. Note: Can call API repeatedly but the maximum number of recipients in the target field on the item is 500 recipients.

  • Mac, web browser: 100 recipients

  • Other: No limit

[ API set: Mailbox 1.1 ]

getAsync(options, callback)

Gets a recipient list for an appointment or message.

When the call completes, the asyncResult.value property will contain an array of EmailAddressDetails objects. Collection size limits:

  • Windows, Mac, web browser: 500 members

  • Other: No limit

[ API set: Mailbox 1.1 ]

getAsync(callback)

Gets a recipient list for an appointment or message.

When the call completes, the asyncResult.value property will contain an array of EmailAddressDetails objects. Collection size limits:

  • Windows, Mac, web browser: 500 members

  • Other: No limit

[ API set: Mailbox 1.1 ]

setAsync(recipients, options, callback)

Sets a recipient list for an appointment or message.

The setAsync method overwrites the current recipient list.

The recipients parameter can be an array of one of the following:

Maximum number that can be set:

  • Windows, Mac, web browser: 100 recipients

  • Other: No limit

[ API set: Mailbox 1.1 ]

setAsync(recipients, callback)

Sets a recipient list for an appointment or message.

The setAsync method overwrites the current recipient list.

The recipients parameter can be an array of one of the following:

Maximum number that can be set:

  • Windows, Mac, web browser: 100 recipients

  • Other: No limit

[ API set: Mailbox 1.1 ]

Method Details

addAsync(recipients, options, callback)

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

The recipients parameter can be an array of one of the following:

Maximum number that can be added:

  • Windows: 100 recipients. Note: Can call API repeatedly but the maximum number of recipients in the target field on the item is 500 recipients.

  • Mac, web browser: 100 recipients

  • Other: No limit

[ API set: Mailbox 1.1 ]

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

Parameters

recipients
(string | EmailUser | EmailAddressDetails)[]

The recipients to add to the recipients list.

options
Office.AsyncContextOptions

Optional. 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 method.

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

Minimum permission level: ReadWriteItem

Applicable Outlook mode: Compose

Errors:

  • NumberOfRecipientsExceeded: The number of recipients exceeded 100 entries.

addAsync(recipients, callback)

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

The recipients parameter can be an array of one of the following:

Maximum number that can be added:

  • Windows: 100 recipients. Note: Can call API repeatedly but the maximum number of recipients in the target field on the item is 500 recipients.

  • Mac, web browser: 100 recipients

  • Other: No limit

[ API set: Mailbox 1.1 ]

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

Parameters

recipients
(string | EmailUser | EmailAddressDetails)[]

The recipients to add to the recipients list.

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

Minimum permission level: ReadWriteItem

Applicable Outlook mode: Compose

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

getAsync(options, callback)

Gets a recipient list for an appointment or message.

When the call completes, the asyncResult.value property will contain an array of EmailAddressDetails objects. Collection size limits:

  • Windows, Mac, web browser: 500 members

  • Other: No limit

[ API set: Mailbox 1.1 ]

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 method.

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

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

Returns

void

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose

getAsync(callback)

Gets a recipient list for an appointment or message.

When the call completes, the asyncResult.value property will contain an array of EmailAddressDetails objects. Collection size limits:

  • Windows, Mac, web browser: 500 members

  • Other: No limit

[ API set: Mailbox 1.1 ]

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

Parameters

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

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

Returns

void

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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) {
    var msgBcc = asyncResult.value;
    console.log("Message being blind-copied to:");
    for (var i = 0; i < msgBcc.length; i++) {
      console.log(msgBcc[i].displayName + " (" + msgBcc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/samples/outlook/30-recipients-and-attendees/get-set-cc-message-compose.yaml
Office.context.mailbox.item.cc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    var msgCc = asyncResult.value;
    console.log("Message being copied to:");
    for (var i = 0; i < msgCc.length; i++) {
      console.log(msgCc[i].displayName + " (" + msgCc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/samples/outlook/30-recipients-and-attendees/get-set-optional-attendees-appointment-organizer.yaml
Office.context.mailbox.item.optionalAttendees.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    var apptOptionalAttendees = asyncResult.value;
    for (var 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);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/samples/outlook/30-recipients-and-attendees/get-set-required-attendees-appointment-organizer.yaml
Office.context.mailbox.item.requiredAttendees.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    var apptRequiredAttendees = asyncResult.value;
    for (var 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);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/samples/outlook/30-recipients-and-attendees/get-set-to-message-compose.yaml
Office.context.mailbox.item.to.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    var msgTo = asyncResult.value;
    console.log("Message being sent to:");
    for (var 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.

The recipients parameter can be an array of one of the following:

Maximum number that can be set:

  • Windows, Mac, web browser: 100 recipients

  • Other: No limit

[ API set: Mailbox 1.1 ]

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

Parameters

recipients
(string | EmailUser | EmailAddressDetails)[]

The recipients to add to the recipients list.

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 method.

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

Minimum permission level: ReadWriteItem

Applicable Outlook mode: Compose

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.

The recipients parameter can be an array of one of the following:

Maximum number that can be set:

  • Windows, Mac, web browser: 100 recipients

  • Other: No limit

[ API set: Mailbox 1.1 ]

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

Parameters

recipients
(string | EmailUser | EmailAddressDetails)[]

The recipients to add to the recipients list.

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

Minimum permission level: ReadWriteItem

Applicable Outlook mode: Compose

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.
var 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/master/samples/outlook/30-recipients-and-attendees/get-set-bcc-message-compose.yaml
var email = $("#emailBcc")
  .val()
  .toString();
var 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);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/samples/outlook/30-recipients-and-attendees/get-set-cc-message-compose.yaml
var email = $("#emailCc")
  .val()
  .toString();
var 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);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/samples/outlook/30-recipients-and-attendees/get-set-optional-attendees-appointment-organizer.yaml
var email = $("#emailOptional")
  .val()
  .toString();
var 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);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/samples/outlook/30-recipients-and-attendees/get-set-required-attendees-appointment-organizer.yaml
var email = $("#emailRequired")
  .val()
  .toString();
var 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);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/samples/outlook/30-recipients-and-attendees/get-set-to-message-compose.yaml
var email = $("#emailTo")
  .val()
  .toString();
var 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);
  }
});