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?
- What is a Recipient?
- When to use Recipients?
- How to work with a recipient
- What are the main properties and methods?
- What events should I typically use?
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.
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.
Public Sub EnumerateRecipients(ByRef email As Outlook._MailItem) Dim recs As Outlook.Recipients = email.Recipients For i As Integer = 1 To recs.Count Dim r As Outlook.Recipient = recs.Item(i) If Not r.Resolved Then r.Resolve() End If Marshal.ReleaseComObject(r) Next Marshal.ReleaseComObject(recs) End Sub
As the procedure accesses each Recipient object, it resolves the recipient address against the Outlook address book.
How to add a recipient
To add a Recipient to an email, you need to access the Recipients collection and call its Add method.
Public Sub AddRecipient(ByRef email As Outlook._MailItem) 'BCC My Self on all emails Dim recs As Outlook.Recipients = email.Recipients Dim r As Outlook.Recipient = recs.Add("Ty Anderson") r.Resolve() Marshal.ReleaseComObject(r) Marshal.ReleaseComObject(recs) End Sub
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.
Public Sub RemoveRecipient(ByRef email As Outlook._MailItem, name As String) Dim recs As Outlook.Recipients = email.Recipients For i As Integer = recs.Count To 1 Step -1 Dim r As Outlook.Recipient = recs.Item(i) If r.Name = name Then recs.Remove(i) End If Marshal.ReleaseComObject(r) Next Marshal.ReleaseComObject(recs) End Sub
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.
Public Sub RetrieveRecipientSMTPAddresses(ByRef email As Outlook._MailItem) 'An assist from: ' https://msdn.microsoft.com/en-us/library/office/ff868695(v=office.15).aspx Dim recs As Outlook.Recipients = email.Recipients Dim stringOfEmails As String = Nothing Const PR_SMTP_ADDRESS As String = "https://schemas.microsoft.com/mapi/proptag/0x39FE001E" For i As Integer = 1 To recs.Count Dim r As Outlook.Recipient = recs.Item(i) Dim pa As Outlook.PropertyAccessor = r.PropertyAccessor If Not r.Resolved Then r.Resolve() stringOfEmails = stringOfEmails & pa.GetProperty(PR_SMTP_ADDRESS) & vbCrLf Marshal.ReleaseComObject(pa) Marshal.ReleaseComObject(r) Next Marshal.ReleaseComObject(recs) MsgBox(stringOfEmails, MsgBoxStyle.OkOnly, "Email Addresses") End Sub
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.
The Delete method achieves the same results as the Recipients.Remove method. The difference is the Delete method belongs to the Recipient object.
Public Sub DeleteExternalAddresses(ByRef email As Outlook._MailItem) Dim recs As Outlook.Recipients = email.Recipients Dim myDomain As String = "add-in-express.com" For i As Integer = recs.Count To 1 Step -1 Dim r As Outlook.Recipient = recs.Item(i) If Not r.Address.Contains(myDomain) Then r.Delete() End If Marshal.ReleaseComObject(r) Next Marshal.ReleaseComObject(recs) End Sub
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.
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.
Public Sub CheckIfFree(ByRef email As Outlook._MailItem) Dim recs As Outlook.Recipients = email.Recipients For i As Integer = 1 To recs.Count Dim r As Outlook.Recipient = recs.Item(i) Dim scheduleInfo As String = r.FreeBusy(Now(), 5) If scheduleInfo.Contains("00") Then Else 'create reminder Dim reminder As Outlook._AppointmentItem = _ OutlookApp.CreateItem(Outlook.OlItemType.olAppointmentItem) With reminder .Subject = "Check that " & r.Address & " read your email." .Start = Now().AddHours(1) .End = Now().AddHours(1) .ReminderSet = True .ReminderMinutesBeforeStart = 0 .Save() End With Marshal.ReleaseComObject(reminder) End If Marshal.ReleaseComObject(r) Next Marshal.ReleaseComObject(recs) End Sub
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.
This sample Outlook add-in was created using Add-in Express for Office and .net: