Office.Recipients interface

Remarks

Minimum permission levelReadItem
Applicable Outlook modeCompose

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:

  • Strings containing SMTP email addresses

  • EmailUser objects

  • EmailAddressDetails objects

[ 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 Office.EmailAddressDetails objects.

[ 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:

[ 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:

  • Strings containing SMTP email addresses

  • EmailUser objects

  • EmailAddressDetails objects

[ API set: Mailbox 1.1 ]

addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options?: Office.AsyncContextOptions, callback?: (result: 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
(result: 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 levelReadWriteItem
Applicable Outlook modeCompose
ErrorsNumberOfRecipientsExceeded - The number of recipients exceeded 100 entries.

In addition to the main signature, this method also has these signatures:

addAsync(recipients: (string | EmailUser | EmailAddressDetails)[]): void;

addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options: Office.AsyncContextOptions): void;

addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], callback: (result: AsyncResult<void>) => void): void;

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) {
        showMessage(result.error);
    } else {
        showMessage("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 Office.EmailAddressDetails objects.

[ API set: Mailbox 1.1 ]

getAsync(options: Office.AsyncContextOptions, callback: (result: AsyncResult<Office.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
(result: AsyncResult<Office.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 levelReadItem
Applicable Outlook modeCompose

In addition to the main signature, this method also has this signature:

getAsync(callback: (result: AsyncResult&lt;Office.EmailAddressDetails[]&gt;) => void): void;

Examples

// The following example gets the optional attendees of a meeting.
Office.context.mailbox.item.optionalAttendees.getAsync(function(result) {
    if (result.error) {
        showMessage(result.error);
    } else {
        var msg = "";
        result.value.forEach(function(recip, index) {
            msg = msg + recip.displayName + " (" + recip.emailAddress + ");";
        });
        showMessage(msg);
    }
});

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:

[ API set: Mailbox 1.1 ]

setAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options?: Office.AsyncContextOptions, callback?: (result: 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
(result: 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 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 levelReadWriteItem
Applicable Outlook modeCompose
ErrorsNumberOfRecipientsExceeded - The number of recipients exceeded 100 entries.

In addition to the main signature, this method also has these signatures:

setAsync(recipients: (string | EmailUser | EmailAddressDetails)[]): void;

setAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options: Office.AsyncContextOptions): void;

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

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) {
        showMessage(result.error);
    } else {
        showMessage("Recipients overwritten");
    }
});