Pieter van der Westhuizen

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?

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

8 Comments

  • https://secure.gravatar.com/avatar/b09e73635f9ffebef24874e165a1333f?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Rafael Fantini says:

    Friend, how do I assign this task to a user. I want my application to create tasks for certain users. Thank you in advance for your attention.

  • https://secure.gravatar.com/avatar/e1a4c2b21a5186e0b27c1c601f418b76?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Pieter van der Westhuizen says:

    Hi Rafael,

    Have a look at the Assign method of the Outlook.TaskItem object. You can assign a task to a contact with the following code:

    Outlook.TaskItem task = null;
    Outlook.Recipients recipients = null;

    try
    {
    task = (Outlook.TaskItem)OutlookApp.CreateItem(Outlook.OlItemType.olTaskItem);
    recipients = task.Recipients;
    task.Subject = “Review site design”;
    task.StartDate = DateTime.Now;
    task.DueDate = DateTime.Now.AddDays(2);
    task.Status = Outlook.OlTaskStatus.olTaskNotStarted;
    task.Assign();
    recipients.Add(“someone@somewhere.net”);
    recipients.ResolveAll();
    task.Send();
    }
    finally
    {
    if (recipients != null) Marshal.ReleaseComObject(recipients);
    if (task != null) Marshal.ReleaseComObject(task);
    }

    Hope this helps and good luck!

  • https://secure.gravatar.com/avatar/b09e73635f9ffebef24874e165a1333f?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Rafael Fantini says:

    Thanks, worked perfectly … :)

    I’m sending a task reminder in the form below, correct?

    task.ReminderSet = true;
    task.ReminderPlaySound = true;
    task.ReminderTime = new DateTime(2013, 11, 20, 10, 30, 00);
    task.Importance = Outlook.OlImportance.olImportanceHigh;

    Thank you ..

  • https://secure.gravatar.com/avatar/e1a4c2b21a5186e0b27c1c601f418b76?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Pieter van der Westhuizen says:

    Great! Good to hear.

    That looks correct, just remember to save your task : )

  • https://secure.gravatar.com/avatar/3dcdc26bf7531b1ecaaebdd009927c29?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Carlos Tomaz says:

    Not sure you can be contacted 3 years after the last post…

    I came across this page and I was wondering if you could please throw some light into the problem I have with DELETE TASK…

    I’ve copied the sample code you’ve provided… However, I don’t understand how outlook know what task to delete…

    I have the task date and other information, but none of it is passed to outlook…

    Are you able to explain how outlook knows what task item I want to delete?

    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();

  • https://secure.gravatar.com/avatar/e1a4c2b21a5186e0b27c1c601f418b76?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Pieter van der Westhuizen says:

    Hi Carlos,

    I’m still around :)

    We get the task by getting the Active Explorer currently selected item:

    currExpl = OutlookApp.ActiveExplorer();
    selection = currExpl.Selection;
    selectedItem = selection[1];

    We then verify that it is actually a task item:

    if (selectedItem is Outlook.TaskItem)

    We then cast it to an Outlook TaskItem and delete it:
    task = selectedItem as Outlook.TaskItem;
    task.Delete();

    Does this answer your question?

  • https://secure.gravatar.com/avatar/3dcdc26bf7531b1ecaaebdd009927c29?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Carlos Tomaz says:

    Hi Pieter,

    Many thanks for taking the time to reply to my request…

    You are talking light-years ahead of what I can understand…

    If you don’t mind talking baby language with me. This is the first time I ever used outlook and I’m not a professional as you are…

    Let me give you some background into what I am trying to achieve:

    1) From within the app I’m coding, my user wants to create tasks on someone else’s outlook task list. The idea is to use outlook as a tool to let the other user know what he/she needs to do on a particular day.

    2) So, following your code on how to create a task, my user “George” managed to create a task “Send EOFY Report to Client” in Laura’s tasklist

    3) So far so go. Laura can accept and/or reject the task, etc… etc…

    4) Now user “George” wants to delete that task, as it is no longer required of Laura to complete it

    What I don’t understand and definitely don’t have a clue how to do it is: How I can access Laura’s tasklist, identify the “Send EOFY Report to Client” and delete it…

    If you understand what I’m trying to achieve, are able to give me some leads or simple code that I can use to test/try???

    In your reply you said “We get the task by getting the Active Explorer currently selected item”. But How do I do that select an item?

    currExpl = OutlookApp.ActiveExplorer(); <– I assume this is the collection that holds Laura's task list, is this correct?
    selection = currExpl.Selection; <– what have I selected?
    selectedItem = selection[1]; <– what is this "1"

    There's no mention anywhere that I want to delete a task from Laura's task list named "Send EOFY Report to Client".

    That's what I don't understand.

    I would expect some kind of "find" in a collection that holds all the tasks of a particular user (Laura) and has "Send EOFY Report to Client" in the task name…

    Are you able to elaborate on this? Please…

  • https://secure.gravatar.com/avatar/e1a4c2b21a5186e0b27c1c601f418b76?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Pieter van der Westhuizen says:

    Hi Carlos,

    From the sound of it, I thnk you might save a lot of work by enabling task sharing for your users.
    User would then be able to create and send tasks to others.

    Take a look at https://support.office.com/en-us/article/Share-task-folders-with-others-2627f41d-84ee-4b7d-adf0-4d3edefac110?ui=en-US&rs=en-US&ad=US
    and https://www.extendoffice.com/documents/outlook/1678-outlook-share-tasks.html
    to see what I mean.

    Would this work for what you have in mind?

Post a comment

Have any questions? Ask us right now!