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. |
| add |
Adds a recipient list to the existing recipients for an appointment or message. |
| get |
Gets a recipient list for an appointment or message. |
| get |
Gets a recipient list for an appointment or message. |
| set |
Sets a recipient list for an appointment or message. The |
| set |
Sets a recipient list for an appointment or message. The |
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
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 Windows, on Mac (classic UI), on the web, on Android, and on iOS. However, take note of the following:
In Outlook on Windows, on Mac (classic UI), and on the web, 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
addAsyncrepeatedly, but be mindful of the recipient limit of the field.In Outlook on Android and on iOS, the
addAsyncmethod 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
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 Windows, on Mac (classic UI), on the web, on Android, and on iOS. However, take note of the following:
In Outlook on Windows, on Mac (classic UI), and on the web, 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
addAsyncrepeatedly, but be mindful of the recipient limit of the field.In Outlook on Android and on iOS, the
addAsyncmethod 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
Minimum permission level: read item
Applicable Outlook mode: 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 object instead of the contact's saved name. For more details, see related GitHub issue.
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
Minimum permission level: read item
Applicable Outlook mode: 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 object instead of the contact's saved name. For more details, see related GitHub issue.
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
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 Windows, on Mac (classic UI), on the web, on Android, and on iOS. However, take note of the following:
In Outlook on Windows, on Mac (classic UI), and on the web, you can have a maximum of 500 recipients in a target field. If you need to set more than 100 recipients, you can call
setAsyncrepeatedly, but be mindful of the recipient limit of the field.In Outlook on Android and on iOS, the
setAsyncmethod 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
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 Windows, on Mac (classic UI), on the web, on Android, and on iOS. However, take note of the following:
In Outlook on Windows, on Mac (classic UI), and on the web, you can have a maximum of 500 recipients in a target field. If you need to set more than 100 recipients, you can call
setAsyncrepeatedly, but be mindful of the recipient limit of the field.In Outlook on Android and on iOS, the
setAsyncmethod 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);
}
});
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for