Using Outlook Recipient and Recipients collection – guide for developers

Writing email can get you in a lot of trouble if you are not paying attention. I can tell you about some seriously funny (on retrospect) situations caused when I inadvertently added a recipient that I did not intend to add. I can tell you but I won’t (unless we meet in person and you buy me a beer). Let’s just say that Outlook’s autofill feature is not your friend and is not to be trusted.

Moving on. Today’s topic is the Outlook Recipient… what is it and what can you do with it?

What is the Outlook Recipients collection?

This will surprise you. The Recipients collection in Outlook is the object that contains all recipients in an email.

What is a Recipient?

I think you know this already. But for the sake of covering all the facts, the Recipient object is a single entry/address within the Recipients collection. For those of you from West Texas (I can make fun of them, I grew up there), Recipients are the email addresses you input in the TO, CC and BCC fields using the Outlook user interface.

When to use Recipients?

Use them anytime you use code to create MailItems (or AppointmentItems).

How to work with a recipient

We’ll follow tradition here and begin with the parent collection. Where there is a Recipient object there is most definitely a Recipients collection.

Enumerate Recipients

The Recipients class is a child of Outlook’s MailItem object. The sample EnumerateRecipients procedure takes a passed MailItem object and loops through its each recipient.

The Add method needs to know the name of the recipient you want to add. After you add them, I recommend you call Resolve.

How to edit recipients

Editing recipients is done by adding or deleting email recipients. Meaning, you already know 50% of the recipients editing routine. I’ll show you the other 50% now.

How to remove a recipient

Removing a recipient is as accessing a MailItem‘s Recipients collection and calling the Remove method. Unfortunately, you can’t pass the name of the recipient you want to remove. Instead, you need to loop through the Recipients collection and compare the Recipient.Name to a passed string.

I’m looping backwards because if I remove an item, the collection’s Count property lowers. Thus, it’s best to start counting at the highest number and work to the lowest.

How to retrieve a recipients SMTP email address

You want to get the SMTP address for a Recipient? Sounds simple but that isn’t necessarily so. Exchange has a peculiar habit of return nonsensical strings when you access the Recipient.Address property. The best method is to access a MAPI property that will reliably provide you with the SMTP email address.

The sample above moves through the Recipients collection and builds a string containing all recipient emails. The trick is to use the Recipient.PropertyAccessor and its GetProperty method (along with the correct MAPI property).

Resolve against the address book

When you use the Outlook user interface to add recipients, sometimes Outlook doesn’t recognize them automatically as a valid email address. The way you know this is the recipient is not underlined. To force Outlook to check the Outlook Address book for matching recipients, you click the Check Names button in the Outlook Ribbons. If Outlook finds a match or the email is a valid email address, Outlook underlines the recipient and considers the recipient resolved. This is the same as calling Recipient.Resolve as I’ve shown in several of the previous examples.

I just wanted to give a proper explanation of what was going on AND to point out Resolve as a valid code sample. You might have missed it earlier as I sort of threw it with other samples. If you missed, check it out. It’s worth knowing.

What are the main properties and methods?

Surprisingly, the Outlook Recipients collection is not property and method “rich”. It’s a bit of a pauper compared to the other Outlook objects. In the samples that follow, I cover the ones that matter.

Delete

The Delete method achieves the same results as the Recipients.Remove method. The difference is the Delete method belongs to the Recipient object.

In the sample above, the code loops through the Recipients collection. For each Recipient, it checks if the recipient’s Address is outside of the company domain. If it is, the code deletes the Recipient.

We don’t need anyone leaking news of upcoming products to the press before the big event.

FreeBusy

Sometimes, when sending email, you might want to know if they are currently available to read your email or not. If not, you might want to create a reminder to check back with that person later. This is just what the following sample does.

The code checks the recipient’s schedule for the next 90 minutes. If they are busy during this time, the code creates an AppointmentItem and sets a reminder (or alert).

What events should I typically use?

None. There aren’t any. The sooner you accept this fact, the better it will go for you.

*******

I’ll admit to not giving Recipients their due. Some of these samples are based upon real issues caused by “bad emailing”. I bet you can think of a few ideas as well from your emailing history. But now, you know you can do something about it.

Great explanation of Recipient! One question though, is it even necessary to Resolve the Recipients? I am running into issues when e-mailing outside of our company and therefore the names are not in my address book. If I do not use Resolve, then the Exchange server should send an error e-mail back to me if the recipients address is errant, correct?

The Resolve method works with an Outlook Address book (exchange, local contacts, etc). If the user is not in any of the address books, the Resolve method will fail.

In my example, I use Resolve because the Recipient.Add method asks for the name of a contact (e.g “Ty Anderson”). I use Resolve to force Outlook to validate the addition against an address book.

If you are only adding an email address to the TO, CC, or BCC fields, you can add the email and send.
But, if you are adding names to the Recipients collection, I recommend trying to Resolve them as you add them. This way, you can respond to a failed Resolve how you choose.

Hi,
Great code samples. Can you help me? When finding out (in VB6 code) that I cannot Resolve and address, I would like to either add it to Address book and carry on or not add it but also not display it. I.e. I want to send the email without any outside “interfering”
Regards,
HWW

I would try to call Recipient.AddressEntry.Update() to save a recipient to the Address book; find details at https://msdn.microsoft.com/en-us/library/office/ff860722%28v=office.15%29.aspx. I don’t think you will be able to do this if the recipient is unresolved. You need to call ResolveAll, delete unresolved recipients, and send the email if there are recipients remaining (otherwise, sending the email will fail).

Dmitry Kostochko said “make sure your project targets Outlook 2007 or higher.” That is not an option for me since I need to target 2003 or higher. Is there a way to avoid getting what the OP called “nonsensical strings when you access the Recipient.Address” from Exchange?

It is an Exchange-based email address. I would suggest that you get the Sender property instead of SenderEmailAddress. The Sender property returns the AddressEntry object and you can use its GetExchangeUser() method to retrieve ExchangeUser.PrimarySmtpAddress.

Hopefully you’re still listening Dmitri!
when email is sent to a distribution list, the recipients list does not include all the addresses – only the distribution email address. Have you ever ran into this?

I a importing emails into Access and was simply going to store as Recipients – not as To, CC, BCC, etc.

This technology is now available for our custom development services only. Based on the Add-in Express for Office core, it is designed for building custom-tailored Office add-ins with far less coding than you usually have to do. Plus, it includes all Add-in Express features such as True RAD, visual designers, Outlook view and form regions, etc.

Get the best platform for building version-neutral, fast and easy deployable plug-ins by using Add-in Express projects templates, visual designers, components and wizards in combination with a perfect Delphi compiler.

This is an extension for Visual Studio that allows developers to quickly create WiX-based setup projects in a familiar Visual Studio way.

The Designer for WiX Toolset lets you forget the plain Windows Installer XML and concentrate on your deployment logic. It integrates several editors with the Visual Studio IDE and provides a set of vdproj designers to configure the file system, registry, user interface, custom actions, launch conditions and more for your setup projects.

The innovative technology for customizing Outlook views and forms. It is included in all Add-in Express for Office products and can be used to extend Outlook views, e-mail, task and appointment windows, To-Do bar, Reading and Navigation panes with your own custom sub-panes.

Microsoft and the Office logo are trademarks or registered trademarks of Microsoft Corporation in
the United States and/or other countries. All other trademarks are property of their respective owners.