HowTo: Deal with the Recipients collection in Outlook

Well, it’s all about Outlook again. Today we will look at the capabilities of the Recipients collection, Recipient and AddressEntry objects. Using these objects you can get all necessary information about recipients, add, remove or modify addressees.

The code samples below are for the MailItem object, but you can easily tweak these examples for working with the TaskItem, AppointmentItem, MeetingItem and JournalItem objects.

1. Getting a list of recipients. To get the recipients we need just 3 things: where to retrieve the recipients from (Outlook MailItem object), the type of needed recipients (olTo, olCC or olBCC) and where to store the recipients’ info (the Items property of the .NET ListBox control in our case):

Private Sub GetRecipients(ByVal mail As Outlook._MailItem,_
  ByVal recipientType As Outlook.OlMailRecipientType,_
  ByVal listBoxItems As ListBox.ObjectCollection)
    listBoxItems.Clear()
    Dim recipients As Outlook.Recipients = mail.Recipients
    If recipients IsNot Nothing Then
        Try
            For i As Integer = 1 To recipients.Count
                Dim recipient As Outlook.Recipient = recipients.Item(i)
                If recipient IsNot Nothing Then
                    Try
                        If recipient.Type = CInt(recipientType) Then
                            Dim entry As Outlook.AddressEntry =_
                              recipient.AddressEntry
                            If entry IsNot Nothing Then
                                Try
                                    If entry.Name.IndexOf("@") < 0 Then
                                        listBoxItems.Add(_
                                          (entry.Name + " (") +_
                                          entry.Address + ")")
                                    Else
                                        listBoxItems.Add(entry.Name)
                                    End If
                                Finally
                                    Marshal.ReleaseComObject(entry)
                                End Try
                            End If
                        End If
                    Finally
                        Marshal.ReleaseComObject(recipient)
                    End Try
                End If
            Next
        Finally
            Marshal.ReleaseComObject(recipients)
        End Try
    End If
End Sub

2. Adding a recipient. To add a recipient you need an Outlook object into which the recipient will be added, name or / and email address of the addressee and the recipient type:

Private Function AddRecipientToMailItem(ByVal mail As Outlook._MailItem,_
  ByVal fullName As String,_
  ByVal recipientType As Outlook.OlMailRecipientType) As Outlook.Recipient
    Dim recipients As Outlook.Recipients = TryCast(_
      mail.Recipients, Outlook.Recipients)
    If recipients IsNot Nothing Then
        Try
            Dim recipient As Outlook.Recipient = TryCast(_
              recipients.Add(fullName), Outlook.Recipient)
            If recipient IsNot Nothing Then
                recipient.Resolve()
                If recipient.Resolved Then
                    recipient.Type = CInt(recipientType)
                    recipients.ResolveAll()
                    Return recipient
                Else
                    recipient.Delete()
                    Return Nothing
                End If
            End If
            Return Nothing
        Finally
            Marshal.ReleaseComObject(recipients)
        End Try
    Else
        Return Nothing
    End If
End Function

3. Removing a recipient. To remove a recipient from the Recipients collection we need to univocally identify that recipient. In the sample below, we use a recipient type (Outlook.OlMailRecipientType.olTo, Outlook.OlMailRecipientType.olCC or Outlook.OlMailRecipientType.olBCC), recipient’s name and email address for such identification:

Private Sub DeleteRecipient(ByVal mailItem As Outlook._MailItem,_
  ByVal recipientType As Outlook.OlMailRecipientType,_
  ByVal recipientFullName As String)
    Dim recipients As Outlook.Recipients = TryCast(_
      mailItem.Recipients, Outlook.Recipients)
    If recipients IsNot Nothing Then
        Try
            Dim fullName As String
            For i As Integer = recipients.Count To 1 Step -1
                Dim recipient As Outlook.Recipient = recipients.Item(i)
                If recipient IsNot Nothing Then
                    Try
                        If recipient.Type = CInt(recipientType) Then
                            Dim entry As Outlook.AddressEntry =_
                              recipient.AddressEntry
                            If entry IsNot Nothing Then
                                Try
                                    If entry.Name.IndexOf("@") < 0 Then
                                        fullName = (entry.Name + " (") +_
                                          entry.Address + ")"
                                    Else
                                        fullName = entry.Name
                                    End If
                                    If fullName.Equals(recipientFullName) Then
                                        recipients.Remove(i)
                                        Exit Try
                                    End If
                                Finally
                                    Marshal.ReleaseComObject(entry)
                                End Try
                            End If
                        End If
                    Finally
                        Marshal.ReleaseComObject(recipient)
                    End Try
                End If
            Next
        Finally
            Marshal.ReleaseComObject(recipients)
        End Try
    End If
End Sub

Well, that seems to be all. Isn’t that hard, is it?

You may also be interested in:

How to develop Outlook COM add-ins
Building Outlook add-in: toolbar, button, ribbon tab, menu

Available downloads:

This sample add-in was developed using
Add-in Express for Microsoft Office and .net

C# sample Outlook add-in for VS 2005
VB.NET sample Outlook add-in for VS 2005