Office.Recipients interface
Represents recipients of an item. Compose mode only.
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose
Methods
| add |
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:
|
| add |
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:
|
| get |
Gets a recipient list for an appointment or message. When the call completes, the
|
| get |
Gets a recipient list for an appointment or message. When the call completes, the
|
| set |
Sets a recipient list for an appointment or message. The The recipients parameter can be an array of one of the following:
Maximum number that can be set:
|
| set |
Sets a recipient list for an appointment or message. The The recipients parameter can be an array of one of the following:
Maximum number that can be set:
|
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
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.
Classic Mac UI, web browser: 100 recipients
New Mac UI, Android: No limit
addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- recipients
-
(string | Office.EmailUser | Office.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 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
Minimum permission level: read/write item
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.
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.
The recipients parameter can be an array of one of the following:
Strings containing SMTP email addresses
EmailUser objects
EmailAddressDetails objects
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.
Classic Mac UI, web browser: 100 recipients
New Mac UI, Android: No limit
addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], callback?: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- recipients
-
(string | Office.EmailUser | Office.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: read/write item
Applicable Outlook mode: Compose
Errors:
NumberOfRecipientsExceeded: The number of recipients exceeded 100 entries.
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, classic Mac UI, web browser: 500 members
New Mac UI, Android: No limit
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 of type Office.AsyncResult. The value property of the result is an array of EmailAddressDetails objects.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose
Important: 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 object instead of the contact's saved name. For more details, refer to the related GitHub issue.
Important: 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.
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, classic Mac UI, web browser: 500 members
New Mac UI, Android: No limit
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 of type Office.AsyncResult. The value property of the result is an array of EmailAddressDetails objects.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose
Important: 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 object instead of the contact's saved name. For more details, refer to the related GitHub issue.
Important: 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.
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.
The recipients parameter can be an array of one of the following:
Strings containing SMTP email addresses
EmailUser objects
EmailAddressDetails objects
Maximum number that can be set:
Windows: 100 recipients. Note: Can call API repeatedly but the maximum number of recipients in the target field on the item is 500 recipients.
Classic Mac UI, web browser: 100 recipients
New Mac UI, Android: No limit
setAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- recipients
-
(string | Office.EmailUser | Office.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 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
Minimum permission level: read/write item
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:
Strings containing SMTP email addresses
EmailUser objects
EmailAddressDetails objects
Maximum number that can be set:
Windows: 100 recipients. Note: Can call API repeatedly but the maximum number of recipients in the target field on the item is 500 recipients.
Classic Mac UI, web browser: 100 recipients
New Mac UI, Android: No limit
setAsync(recipients: (string | EmailUser | EmailAddressDetails)[], callback: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- recipients
-
(string | Office.EmailUser | Office.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: read/write item
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.
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);
}
});
Feedback
Submit and view feedback for