Working with Outlook tasks: how to create, get and delete Task and To-Do items

Outlook tasks are a great way to keep track of things you need to do. I use it every single day! A task item is a standard Outlook type and by default all tasks are flagged for follow-up when created. When any items such as an e-mail, task or contact are flagged for follow-up it automatically becomes a to-do item and is visible in your To-Do bar.

• What is an Outlook task and To-Do item?
• Getting a list of tasks
• Getting a list of To-Do items
• Creating a new Outlook task item
• Creating a new To-Do item
• Creating a recurring task
• Deleting a task item
• Useful events

What is an Outlook task and To-Do item?

Outlook’s To-do items were first introduced in Outlook 2007 and although they might look similar to Tasks, they are inherently different. Outlook tasks are a specific built-in Outlook item type that can have a start and end date, a status as well as a specific recurrence pattern.

Whereas Outlook To-Do items can be either an e-mail or a contact item and they cannot have a start date, end date or a recurrence pattern. Another confusing fact is that Tasks are always To-do items, but To-do items are not always tasks.

Confused yet? Don’t lose hope, let’s take a closer look at using these items in your Office add-ins.

How to get a list of tasks

To get a list of tasks you can use the Outlook Namespace object to get a reference to the default Tasks folder. Take note this will only return the task items in the default Tasks folder and won’t return any To-do items.

C# code example

Outlook.NameSpace ns = null;
Outlook.MAPIFolder tasksFolder = null;
Outlook.Items taskFolderItems = null;
Outlook.TaskItem task = null;
string taskString = string.Empty;
 
try
{
    ns = OutlookApp.Session;
    tasksFolder = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderTasks);
    taskFolderItems = tasksFolder.Items;
 
    for (int i = 1; i <= taskFolderItems.Count; i++)
    {
        task = taskFolderItems[i] as Outlook.TaskItem;
        if (task != null)
        {
            taskString += String.Format("{0} Due: {1}{2}",
                task.Subject, task.DueDate, Environment.NewLine);
            Marshal.ReleaseComObject(task);
        }
    }
    MessageBox.Show(taskString);
}
finally
{
    if (taskFolderItems != null)
        Marshal.ReleaseComObject(taskFolderItems);
    if (tasksFolder != null)
        Marshal.ReleaseComObject(tasksFolder);
    if (ns != null)
        Marshal.ReleaseComObject(ns);
}

How to get a list of To-Do items

It is easy to confuse a To-do item with a task, but bear in mind that a To-do item can either be an e-mail, contact or task. An Outlook item becomes a to-do item as soon as you flag it for follow-up. To get a list of to-do items use the Outlook Namespace object to get a reference to the default to-do folder. Be careful though, you need to check the type of the objects before accessing their properties!

C# code example

Outlook.NameSpace ns = null;
Outlook.MAPIFolder todoFolder = null;
Outlook.Items todoFolderItems = null;
Outlook.TaskItem task = null;
Outlook.ContactItem contact = null;
Outlook.MailItem email = null;
string todoString = string.Empty;
 
try
{
    ns = OutlookApp.Session;
    todoFolder = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderToDo);
    todoFolderItems = todoFolder.Items;
 
    for (int i = 1; i <= todoFolderItems.Count; i++)
    {
        object outlookItem = todoFolderItems[i];
        if (outlookItem is Outlook.MailItem)
        {
            email = outlookItem as Outlook.MailItem;
            todoString += String.Format("Email: {0} Due:{1}{2}",
                email.Subject, email.TaskDueDate, Environment.NewLine);
        }
        else if (outlookItem is Outlook.ContactItem)
        {
            contact = outlookItem as Outlook.ContactItem;
            todoString += String.Format("Contact: {0} Due:{1}{2}",
                contact.FullName, contact.TaskDueDate, Environment.NewLine);
        }
        else if (outlookItem is Outlook.TaskItem)
        {
            task = outlookItem as Outlook.TaskItem;
            todoString += String.Format("Task: {0} Due: {1}{2}",
                task.Subject, task.DueDate, Environment.NewLine);
        }
        else
            MessageBox.Show("Unknown Item type");
        Marshal.ReleaseComObject(outlookItem);
    }
    MessageBox.Show(todoString);
}
finally
{
    if (todoFolderItems != null)
        Marshal.ReleaseComObject(todoFolderItems);
    if (todoFolder != null)
        Marshal.ReleaseComObject(todoFolder);
    if (ns != null)
        Marshal.ReleaseComObject(ns);
}

Creating a new Outlook task item

Creating an Outlook task is a straight forward action if you are using the Outlook Application object’s CreateItem method.

C# code example

Outlook.TaskItem task = null;
 
try
{
    task = (Outlook.TaskItem)OutlookApp.CreateItem(Outlook.OlItemType.olTaskItem);
    task.Subject = "Review site design";
    task.StartDate = DateTime.Now();
    task.DueDate = DateTime.Now.AddDays(2);
    task.Status = Outlook.OlTaskStatus.olTaskNotStarted;
    task.Save();
}
finally
{
    if (task != null)
        Marshal.ReleaseComObject(task);
}

Creating a new To-Do item

We create a new Outlook to-do item by using the MarkAsTask method as shown in the code below:

C# code example

Outlook.Inspector currInsp = null;
Outlook.MailItem mail = null;
 
try
{
    currInsp = OutlookApp.ActiveInspector();
    mail = (Outlook.MailItem)currInsp.CurrentItem;
    mail.MarkAsTask(Outlook.OlMarkInterval.olMarkToday);
}
finally
{
    if (mail != null)
        Marshal.ReleaseComObject(mail);
    if (currInsp != null)
        Marshal.ReleaseComObject(currInsp);
}

Creating a recurring task

A recurring task can repeat at pre-set intervals or can be based on a date that you set the task to complete by. You do this by first creating a new task and then calling the GetRecurrencePattern method.

C# code example

Outlook.TaskItem task = null;
Outlook.RecurrencePattern recPattern = null;
 
try
{
    task = (Outlook.TaskItem)OutlookApp.CreateItem(Outlook.OlItemType.olTaskItem);
    task.Subject = "Do billing";
    task.StartDate = new DateTime(2013, 06, 25);
    task.DueDate = new DateTime(2013, 06, 25);
    task.Status = Outlook.OlTaskStatus.olTaskNotStarted;
 
    recPattern = task.GetRecurrencePattern();
    recPattern.RecurrenceType = Outlook.OlRecurrenceType.olRecursMonthly;
    recPattern.PatternStartDate = new DateTime(2013, 07, 25);
    recPattern.NoEndDate = true;
    task.Save();
}
finally
{
    if (recPattern != null)
        Marshal.ReleaseComObject(recPattern);
    if (task != null)
        Marshal.ReleaseComObject(task);
}

Deleting a task item

In the next example, we first check whether the task is recurring by checking the IsRecurring property and then clearing the recurrence pattern by using the ClearRecurrencePattern method. We then simply delete the task by calling its Delete method.

C# code example

Outlook.Explorer currExpl = null;
Outlook.Selection selection = null;
object selectedItem = null;
Outlook.TaskItem task = null;
 
try
{
    currExpl = OutlookApp.ActiveExplorer();
    selection = currExpl.Selection;
    selectedItem = selection[1];
 
    if (selectedItem is Outlook.TaskItem)
    {
        task = selectedItem as Outlook.TaskItem;
        if (task.IsRecurring)
            task.ClearRecurrencePattern();
        task.Delete();
    }
}
finally
{
    if (selectedItem != null)
        Marshal.ReleaseComObject(selectedItem);
    if (selection != null)
        Marshal.ReleaseComObject(selection);
    if (currExpl != null)
        Marshal.ReleaseComObject(currExpl);
}

Useful events

The Outlook task item exposes a number of standard Item events as explained in depth in our Outlook Item events explained article. However, let’s take a look at using some events with tasks.

You can use the items collection events to determine when certain events occur with tasks. To determine when a task is added, you can use the ItemAdd event:

Outlook.TaskItem task = null; 
 
try 
{ 
    if (Item is Outlook.TaskItem) 
    { 
        task = Item as Outlook.TaskItem; 
        MessageBox.Show(
            String.Format("A new task,called {0} was created. Start date is{1}",
                task.Subject, task.StartDate)); 
    } 
} 
finally 
{ 
    if (task != null) 
        Marshal.ReleaseComObject(task); 
}

To determine when a task item in the Items collection was changed use the ItemChange event:

Outlook.TaskItem task = null;
 
try
{
    if (Item is Outlook.TaskItem)
    {
        task = Item as Outlook.TaskItem;
        MessageBox.Show(String.Format("A task,called {0} was changed.", task.Subject));
    }
}
finally
{
    if (task != null)
        Marshal.ReleaseComObject(task);
}

Thank you for reading. Until next time, keep coding!

Available downloads:

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

C# Outlook Tasks example

Outlook 2013 add-in development in Visual Studio 2012 for beginners

• Part 1: Outlook add-in development: Outlook Application and base objects
• Part 2: Creating custom Outlook views
• Part 3: Creating custom Outlook forms
• Part 4: Outlook UI – Explorer and Inspector Windows. What is customizable?
• Part 5: Customizing Outlook main menu, context menus and Backstage view
• Part 6: Creating custom Outlook ribbons and toolbars
• Part 7: Advanced view regions for Outlook 2013 – 2003
• Part 8: Advanced form regions for Outlook 2013 – 2003
• Part 9: Working with Outlook Accounts, Stores, Folders and Items
• Part 10: Working with Outlook calendar