Eugene Astafiev

How To: Create a new distribution list item in Outlook

Sometimes Outlook users need to send their e-mails to the same recipients. The Outlook Object Model provides the DistListItem class exactly for this task. The distribution list represents a group of contacts that are related in some way. Using distribution lists users can set the TO, CC and BCC fields and send e-mails as they normally do. Let’s consider in depth how to create a distribution list in your profile programmatically with VSTO and Add-in Express for Office and .net.

There is no difference between creating a single contact item or a distribution list item. Distribution lists are stored in the Contacts folder too (I mean personal distribution lists). Note, you can send them to others if needed. If you use an Exchange server in the profile, the Global Address List can contain global distribution lists. They are available to everyone connected to the Exchange server.

The process of creating Outlook distribution lists is fairly simple. Some time ago we discussed how to create a new contact item programmatically. The similar steps are used for creating distribution list items in Outlook:

      1. The simplest way is to use the CreateItem method of the Application class. This method accepts a constant from the OlItemType enumeration and returns a newly created distribution list.
      2. The Items class provides the Add method which does the job. A newly created distribution list is always created in the default Contacts folder regardless of the Items collection we use (frankly speaking, the collection may come from any folder).
      3. We can use a template for creating a new distribution list. The Application class has the CreateItemFromTemplate method for this task. In one of my previous articles I described how to create a message based on a template. The method accepts a string representing file path to the Outlook template (.oft) as a parameter. My tests against Outlook 2010 show that you can pass an msg file as a template too.

After we created a new distribution list we need to add some recipients to it. We do this using the AddMembers method of the DistListItem class. It accepts an instance of the Recipients class and doesn’t return anything. We can create a single instance of the Recipient class using the Outlook Object Model classes. But how can we create an instance of the Recipients class? There is no way. The fact is that the Outlook Object Model doesn’t provide any method for this. Starting from Outlook 2002 the AddMember method can be used for adding a singular recipient, as a workaround. In case of version-neutral interop libraries I suggest using the following approach:

      1. Create a new temporarily Outlook mail item.
      2. Get a recipients collection from the newly created mail item.
      3. Add recipients to the collection.
      4. Add the recipients collection to the distribution list.
      5. Delete the mail item object created on step 1.

I know it is a long way… But it works like charm in case of Outlook 2000.

Don’t forget to pass an instance of the Application class to the CreateNewDistributionList method if you want to get the code running correctly.

C# & Add-in Express:

private void CreateNewDistributionList(Outlook._Application OutlookApp)
{
    Outlook.NameSpace ns = null;
    Outlook.MAPIFolder folderContacts = null;
    Outlook.Items contactItems = null;           
    Outlook.MailItem mail = null;
    Outlook.Recipients listRecipients = null;
    Outlook.DistListItem distributionList = null;
    try
    {
        ns = OutlookApp.GetNamespace("MAPI");
        folderContacts = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderContacts);                
        contactItems = folderContacts.Items;
        // create a new e-mail message to access the recipients collection 
        mail = contactItems.Add(Outlook.OlItemType.olMailItem) as Outlook.MailItem;
        listRecipients = mail.Recipients;
        listRecipients.Add("Andrei Smolin");
        listRecipients.Add("Eugene Astafiev");
        listRecipients.Add("Dmitry Kostochko");               
        if(!listRecipients.ResolveAll())
        {
            System.Windows.Forms.MessageBox.Show("There are no such contact names. "+
               "Please make sure that you have corresponding records in your address book",
               "Add-in Express", MessageBoxButtons.OK, MessageBoxIcon.Warning);
            return;
        }
        // create a new distribution list item
        distributionList = contactItems.Add(Outlook.OlItemType.olDistributionListItem) 
                                                              as Outlook.DistListItem;       
       // distributionList = OutlookApp.CreateItem(Outlook.OlItemType.olDistributionListItem) 
       //                                                            as Outlook.DistListItem;
       // distributionList = OutlookApp.CreateItemFromTemplate("D:\\Add-in Express Team.oft") 
       //                                                            as Outlook.DistListItem;        
        distributionList.DLName = "Add-in Express Team";                    
        distributionList.AddMembers(listRecipients);
        distributionList.Save();
        distributionList.Display(true);                
    }
    catch (Exception ex)
    {
        System.Windows.Forms.MessageBox.Show(ex.Message, 
           "An exception is thrown...", MessageBoxButtons.OK, MessageBoxIcon.Error);
    }
    finally
    {
        if (distributionList != null) Marshal.ReleaseComObject(distributionList);
        if (listRecipients != null) Marshal.ReleaseComObject(listRecipients);
        if (mail != null)
        {
            mail.Delete();
            Marshal.ReleaseComObject(mail);
        }
        if (contactItems != null) Marshal.ReleaseComObject(contactItems);
        if (folderContacts != null) Marshal.ReleaseComObject(folderContacts);
        if (ns != null) Marshal.ReleaseComObject(ns);
    }
}

C# & VSTO:

using System.Windows.Forms;
using System.Runtime.InteropServices;
//
private void CreateNewDistributionList(Outlook.Application Application)
{
    Outlook.NameSpace ns = null;
    Outlook.MAPIFolder folderContacts = null;
    Outlook.Items contactItems = null;
    Outlook.MailItem mail = null;
    Outlook.Recipients listRecipients = null;
    Outlook.DistListItem distributionList = null;
    try
    {
        ns = Application.GetNamespace("MAPI");
        folderContacts = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderContacts);
        contactItems = folderContacts.Items;
        // create a new e-mail message to access the recipients collection 
        mail = contactItems.Add(Outlook.OlItemType.olMailItem) as Outlook.MailItem;
        listRecipients = mail.Recipients;
        listRecipients.Add("Andrei Smolin");
        listRecipients.Add("Eugene Astafiev");
        listRecipients.Add("Dmitry Kostochko");
        if (!listRecipients.ResolveAll())
        {
            System.Windows.Forms.MessageBox.Show("There are no such contact names. " +
               "Please make sure that you have corresponding records in your address book",
               "Add-in Express", MessageBoxButtons.OK, MessageBoxIcon.Warning);
            return;
        }
        distributionList = contactItems.Add(Outlook.OlItemType.olDistributionListItem) 
                                                              as Outlook.DistListItem;
       // distributionList = OutlookApp.CreateItem(Outlook.OlItemType.olDistributionListItem) 
       //                                                            as Outlook.DistListItem;
       // distributionList = OutlookApp.CreateItemFromTemplate("D:\\Add-in Express Team.oft") 
       //                                                            as Outlook.DistListItem;
        distributionList.DLName = "Add-in Express Team";
        distributionList.AddMembers(listRecipients);
        distributionList.Save();
        distributionList.Display(true);
    }
    catch (Exception ex)
    {
        System.Windows.Forms.MessageBox.Show(ex.Message,
           "An exception is thrown...", MessageBoxButtons.OK, MessageBoxIcon.Error);
    }
    finally
    {
        if (distributionList != null) Marshal.ReleaseComObject(distributionList);
        if (listRecipients != null) Marshal.ReleaseComObject(listRecipients);
        if (mail != null)
        {
            mail.Delete();
            Marshal.ReleaseComObject(mail);
        }
        if (contactItems != null) Marshal.ReleaseComObject(contactItems);
        if (folderContacts != null) Marshal.ReleaseComObject(folderContacts);
        if (ns != null) Marshal.ReleaseComObject(ns);
    }
}

VB.NET & Add-in Express:

Private Sub CreateNewDistributionList(ByRef OutlookApp As Outlook._Application)
    Dim ns As Outlook.NameSpace = Nothing
    Dim folderContacts As Outlook.MAPIFolder = Nothing
    Dim contactItems As Outlook.Items = Nothing
    Dim mail As Outlook.MailItem = Nothing
    Dim listRecipients As Outlook.Recipients = Nothing
    Dim distributionList As Outlook.DistListItem = Nothing
    Try
        ns = OutlookApp.GetNamespace("MAPI")
        folderContacts = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderContacts)
        contactItems = folderContacts.Items
        ' create a new e-mail message to access the recipients collection 
        mail = contactItems.Add(Outlook.OlItemType.olMailItem)
        listRecipients = mail.Recipients
        listRecipients.Add("Andrei Smolin")
        listRecipients.Add("Eugene Astafiev")
        listRecipients.Add("Dmitry Kostochko")
        If Not listRecipients.ResolveAll() Then
            System.Windows.Forms.MessageBox.Show("There are no such contact names. " + _
               "Please make sure that you have corresponding records in your address book",
               "Add-in Express", MessageBoxButtons.OK, MessageBoxIcon.Warning)
            Return
        End If
        distributionList = contactItems.Add(Outlook.OlItemType.olDistributionListItem)
        ' distributionList = OutlookApp.CreateItem(Outlook.OlItemType.olDistributionListItem)
        ' distributionList = OutlookApp.CreateItemFromTemplate("D:\Add-in Express Team.oft")
        distributionList.DLName = "Add-in Express Team"
        distributionList.AddMembers(listRecipients)
        distributionList.Save()
        distributionList.Display(True)
    Catch ex As Exception
        System.Windows.Forms.MessageBox.Show(ex.Message,
           "An exception is thrown...", MessageBoxButtons.OK, MessageBoxIcon.Error)
    Finally
        If Not IsNothing(distributionList) Then Marshal.ReleaseComObject(distributionList)
        If Not IsNothing(listRecipients) Then Marshal.ReleaseComObject(listRecipients)
        If Not IsNothing(mail) Then
            mail.Delete()
            Marshal.ReleaseComObject(mail)
        End If
        If Not IsNothing(contactItems) Then Marshal.ReleaseComObject(contactItems)
        If Not IsNothing(folderContacts) Then Marshal.ReleaseComObject(folderContacts)
        If Not IsNothing(ns) Then Marshal.ReleaseComObject(ns)
    End Try
End Sub

VB.NET & VSTO:

Imports System.Windows.Forms
Imports System.Runtime.InteropServices
'
Private Sub CreateNewDistributionList(ByRef Application As Outlook.Application)
    Dim ns As Outlook.NameSpace = Nothing
    Dim folderContacts As Outlook.MAPIFolder = Nothing
    Dim contactItems As Outlook.Items = Nothing
    Dim mail As Outlook.MailItem = Nothing
    Dim listRecipients As Outlook.Recipients = Nothing
    Dim distributionList As Outlook.DistListItem = Nothing
    Try
        ns = Application.GetNamespace("MAPI")
        folderContacts = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderContacts)
        contactItems = folderContacts.Items
        ' create a new e-mail message to access the recipients collection 
        mail = contactItems.Add(Outlook.OlItemType.olMailItem)
        listRecipients = mail.Recipients
        listRecipients.Add("Andrei Smolin")
        listRecipients.Add("Eugene Astafiev")
        listRecipients.Add("Dmitry Kostochko")
        If Not listRecipients.ResolveAll() Then
            System.Windows.Forms.MessageBox.Show("There are no such contact names. " + _
               "Please make sure that you have corresponding records in your address book",
               "Add-in Express", MessageBoxButtons.OK, MessageBoxIcon.Warning)
            Return
        End If
        distributionList = contactItems.Add(Outlook.OlItemType.olDistributionListItem)
        ' distributionList = OutlookApp.CreateItem(Outlook.OlItemType.olDistributionListItem)
        ' distributionList = OutlookApp.CreateItemFromTemplate("D:\Add-in Express Team.oft")
        distributionList.DLName = "Add-in Express Team"
        distributionList.AddMembers(listRecipients)
        distributionList.Save()
        distributionList.Display(True)
    Catch ex As Exception
        System.Windows.Forms.MessageBox.Show(ex.Message,
          "An exception is thrown...", MessageBoxButtons.OK, MessageBoxIcon.Error)
    Finally
        If Not IsNothing(distributionList) Then Marshal.ReleaseComObject(distributionList)
        If Not IsNothing(listRecipients) Then Marshal.ReleaseComObject(listRecipients)
        If Not IsNothing(mail) Then
            mail.Delete()
            Marshal.ReleaseComObject(mail)
        End If
        If Not IsNothing(contactItems) Then Marshal.ReleaseComObject(contactItems)
        If Not IsNothing(folderContacts) Then Marshal.ReleaseComObject(folderContacts)
        If Not IsNothing(ns) Then Marshal.ReleaseComObject(ns)
    End Try
End Sub

See you on our forums and in the e-mail support!

8 Comments

Post a comment

Have any questions? Ask us right now!