Common mail tasks using an Office 365 client library

Last modified: February 12, 2015

Applies to: Exchange Online | Office 365

The Office 365 APIs .NET and Cordova JavaScript client libraries can make it easier interact with the REST APIs. They help manage authentication tokens, simplify the code needed to query and consume data, and perform discovery. You can get the libraries in the latest version of Office 365 API Tools for Visual Studio.

Alternatively, you can use the Mail REST APIs to interact with Office 365 mail data.

Note If you develop apps for Office 365 in China, see API endpoints of Office 365 for China for the specification of the required URLs.

Use a client library to access the Mail API

To access the Mail API by using the .NET or JavaScript client library, you need to acquire an access token and get the Outlook Services client. Then, you can send async queries to interact with mail data.

Get an access token | Get the Outlook Services client

Get messages | Send new messages | Reply to messages | Forward messages | Update messages | Delete messages | Move or copy messages | Get attachments

Get folders | Create folders | Update folders | Delete folders | Move or copy folders

Get an access token

Acquire the access token used for authentication. The client ID and authorization URI are assigned when you register your app with Microsoft Azure Active Directory.

Note This pattern applies only to code that runs on Windows devices. In a Windows Store App, values for ClientID and AuthorizationUri are added to your project's App.xaml file when you register your application. AuthorizationUri is used as the host name for the CommonAuthority variable.

// Properties of the native client app. Get the ClientId from the resources section of the App.xaml file.
public const string ClientID = Application.Current.Resources["ida:ClientID"] as String; 
// Get the _returnUri from app settings.
public static Uri _returnUri = Windows.Security.Authentication.Web.WebAuthenticationBroker.GetCurrentApplicationCallbackUri();

// Properties used to communicate with a Windows Azure AD tenant.  
public const string CommonAuthority = "https://login.windows.net/Common"; 
public const string DiscoveryResourceId = "https://api.office.com/discovery/"; 

//Store authority in application data so that it isn't tied to the lifetime of the access token.
private static ApplicationDataContainer _settings = ApplicationData.Current.LocalSettings;
private static string LastAuthority
{
    get
    {
        if (_settings.Values.ContainsKey("LastAuthority") && _settings.Values["LastAuthority"] != null)
        {
            return _settings.Values["LastAuthority"].ToString();
        }
        else
        {
            return string.Empty;
        }

    }

    set
    {
        _settings.Values["LastAuthority"] = value;
    }
}

public static AuthenticationContext _authenticationContext { get; set; } 
private static async Task<string> GetTokenHelperAsync(AuthenticationContext context, string resourceId)
{
    string accessToken = null;
    AuthenticationResult result = null;

    result = await context.AcquireTokenAsync(resourceId, ClientID, _returnUri);

    accessToken = result.AccessToken;
    //Store authority in application data.
    _settings.Values["LastAuthority"] = context.Authority;

    return accessToken;
}
var authContext;
var authToken; // for use with creating an outlookClient later.
authContext = new O365Auth.Context();
authContext.getIdToken("https://outlook.office365.com/")
   .then((function (token) {
       authToken = token;
       // The auth token also carries additional information. For example:    
       userName = token.givenName + " " + token.familyName;
   }).bind(this), function (reason) {
       console.log('Failed to login. Error = ' + reason.message);
   });

Get the Outlook Services client

Get the OutlookServicesClient object. You can call this code from other methods that use the Outlook Services client.

public static async Task<OutlookServicesClient> CreateOutlookClientAsync(string capability)
{
    try
    {
        //First, look for the authority used during the last authentication.
        //If that value is not populated, use CommonAuthority.
        string authority = null;
        if (String.IsNullOrEmpty(LastAuthority))
        {
            authority = CommonAuthority;
        }
        else
        {
            authority = LastAuthority;
        }
        // Create an AuthenticationContext using this authority.
        _authenticationContext = new AuthenticationContext(authority);

        //See the Discovery Service Sample (https://github.com/OfficeDev/Office365-Discovery-Service-Sample)
        //for an approach that improves performance by storing the discovery service information in a cache.
        DiscoveryClient discoveryClient = new DiscoveryClient(
            async () => await GetTokenHelperAsync(_authenticationContext, DiscoveryResourceId));

        // Get the specified capability ("Mail").
        CapabilityDiscoveryResult result = 
            await discoveryClient.DiscoverCapabilityAsync(capability);
        var client = new OutlookServicesClient(
            result.ServiceEndpointUri,
            async () => 
                await GetTokenHelperAsync(_authenticationContext, result.ServiceResourceId));
        return client;
    }
    catch (Exception)
    {
        if (_authenticationContext != null && _authenticationContext.TokenCache != null)
        _authenticationContext.TokenCache.Clear();
        return null;
    }
}
// Once the authToken has been acquired, create an outlookClient. One place to do this is inside of the
//    ".then" function callback of authContext.getIdToken(...) above.
var outlookClient = new Microsoft.OutlookServices.Client('https://outlook.office365.com/api/v1.0', authToken.getAccessTokenFn('https://outlook.office365.com'));

Get messages

Get the messages in the Inbox by using the Me.Messages shortcut property. To get the messages from a different folder, use the folder's Messages property. You can use the following well-known folder names instead of the ID for the corresponding folder: Inbox, SentItems, Drafts, DeletedItems.

Example: outlookClient.Me.Folders["SentItems"].Messages.ExecuteAsync()

To get a particular message, specify the message ID as the index of the Messages collection or use the GetById method.

Note Message collections support query expressions such as Select, OrderBy, and Take.

This example calls the method that creates the Outlook Services client.

var outlookClient = await CreateOutlookClientAsync("Mail");
    var messages = await outlookClient.Me.Folders["Inbox"].Messages
      .OrderByDescending(m => m.DateTimeReceived)
      .Take(10)
      .ExecuteAsync();

foreach(var message in messages.CurrentPage)
{
  System.Diagnostics.Debug.WriteLine("Message '{0}' received at '{1}'.",
    message.Subject,
    message.DateTimeReceived.ToString());
}
outlookClient.me.folders.getFolder('Inbox').messages.getMessages().orderBy('DateTimeReceived desc').fetchAll(10).then(function (result) {
    result.forEach(function (message) {
        console.log('Message "' + message.subject + '" received at "' + message.dateTimeReceived.toString() + '"');
    });
}, function(error) {
    console.log(error);
});

Send new or drafted messages

You can send a new message on the fly with a supplied message or create draft message and then send it.

Send a new message on the fly

Create a message and pass it to the SendMailAsync method.

This example assumes you already got the Outlook Services client.

ItemBody body = new ItemBody
{
    Content = "It was <b>awesome</b>!",
    ContentType = BodyType.HTML
};
List<Recipient> toRecipients = new List<Recipient>();
toRecipients.Add(new Recipient
{
    EmailAddress = new EmailAddress
    {
        Address = "katiej@a830edad9050849NDA1.onmicrosoft.com"
    }
});
toRecipients.Add(new Recipient
{
    EmailAddress = new EmailAddress
    {
        Address = "pavelb@a830edad9050849NDA1.onmicrosoft.com"
    }
});
Message newMessage = new Message
{
    Subject = "Did you see last night's game?",
    Body = body,
    ToRecipients = toRecipients
};

// To send a message without saving to Sent Items, specify false for  
// the SavetoSentItems parameter. 
await outlookClient.Me.SendMailAsync(newMessage, true);

Create a draft message

Create a draft message and pass it to the AddMessageAsync method. Then you can update the draft and send it.

This example assumes you already got the Outlook Services client.

ItemBody body = new ItemBody
{
    Content = "I'm coming out a week later.",
    ContentType = BodyType.HTML
};
List<Recipient> toRecipients = new List<Recipient>();
toRecipients.Add(new Recipient
{
    EmailAddress = new EmailAddress
    {
        Address = "katiej@a830edad9050849NDA1.onmicrosoft.com"
    }
});
Message draftMessage = new Message
{
    Subject = "Changed my travel plans",
    Body = body,
    ToRecipients = toRecipients,
    Importance = Importance.High
};

// Save the draft message. Saving to Me.Messages saves the message in the Drafts folder.
await outlookClient.Me.Messages.AddMessageAsync(draftMessage);

// Get the ID of the message.
string messageId = draftMessage.Id;

Adding a message to the Me.Messages collection saves the draft in the Drafts folder, but you can save a draft in the Messages collection of any folder.

Example: outlookClient.Me.Folders["AAMkADE3N..."].Messages.AddMessageAsync(newMessage)

Send a draft message

Send a draft message by calling SendAsync. You can send a draft of a new, reply, reply-all, or forward message.

This example assumes you already got the Outlook Services client and got the message ID.

await outlookClient.Me.Messages[messageId].SendAsync();

Reply or ReplyAll to messages

You can reply to a message directly or create a draft reply message and then send it.

Reply to a message directly

Reply directly to the sender of the message or to all recipients by calling ReplyAsync or ReplyAllAsync and passing in a comment.

This example assumes you already got the Outlook Services client and got the message ID.

await outlookClient.Me.Messages[messageId].ReplyAsync("Count me in.");
await outlookClient.Me.Messages[messageId].ReplyAllAsync("Count me in.");

Create a draft Reply or ReplyAll message

Create a draft Reply or ReplyAll message by calling CreateReplyAsync or CreateReplyAllAsync. Then you can update the draft and send it.

This example assumes you already got the Outlook Services client and got the message ID.

IMessage replyDraft = await outlookClient.Me.Messages[messageId].CreateReplyAsync();

// Get the ID of the draft Reply message.
string replyMessageId = replyDraft.Id;
IMessage replyAllDraft = await outlookClient.Me.Messages[messageId].CreateReplyAllAsync();

// Get the ID of the draft Reply All message.
string replyAllMessageId = replyAllDraft.Id;

CreateReplyAsync and CreateReplyAllAsync create a draft message with the ToRecipients, IsDraft, and other appropriate properties prepopulated.

Forward new or drafted messages

You can forward a message directly or create a draft forward message and then send it.

Forward a message directly

Forward a message directly by calling ForwardAsync and passing in a comment and the recipients.

This example assumes you already got the Outlook Services client and got the message ID.

List<Recipient> recipients = new List<Recipient>();
recipients.Add(new Recipient
{
    EmailAddress = new EmailAddress
    {
        Address = "garthf@a830edad9050849NDA1.onmicrosoft.com"
    }
});
await outlookClient.Me.Messages[messageId].ForwardAsync("Interested?", recipients);

Create a draft Forward message

Create a draft Forward message by calling CreateForwardAsync. Then you can update the draft and send it.

This example assumes you already got the Outlook Services client and got the message ID.

IMessage forwardDraft = await outlookClient.Me.Messages[messageId].CreateForwardAsync();

// Get the ID of the draft Forward message.
string forwardMessageId = forwardDraft.Id;

CreateForward creates a draft message with the IsDraft and other appropriate properties prepopulated.

Update messages

Change writable properties on a message, and call UpdateAsync to save the changes.

This example assumes you already got the Outlook Services client and got the message ID.

IMessage message = await outlookClient.Me.Messages[messageId].ExecuteAsync();
message.Body = new ItemBody
{
        Content = "I'm coming out a week earlier."
};
message.ToRecipients.Add(new Recipient
{
    EmailAddress = new EmailAddress
    {
        Address = "garthf@a830edad9050849NDA1.onmicrosoft.com"
    }
});
await message.UpdateAsync();

You can define multiple updates client-side and send the requests all at once (batch them) by using the following pattern:

  1. Call UpdateAsync(true) for each entity you want to update. Specifying true registers the updates locally on the client but doesn't post them to the server.
  2. Call outlookClient.Context.SaveChangesAsync() to post all updates that are registered locally.

Delete messages

Delete a message by calling DeleteAsync.

This example assumes you already got the Outlook Services client and got the message ID.

IMessage message = await outlookClient.Me.Messages[messageId].ExecuteAsync();
await message.DeleteAsync();

Move or copy messages

Move a or copy a message by passing the ID of the destination folder to the MoveAsync or CopyAsync method.

This example assumes you already got the Outlook Services client, got the message ID, and got the desination folder ID.

IMessage messageToMove = await outlookClient.Me.Messages[messageId].ExecuteAsync();
await messageToMove.MoveAsync("AAMkADE3N...");
IMessage messageToCopy = await outlookClient.Me.Messages[messageId].ExecuteAsync();
await messageToCopy.CopyAsync("Inbox");

Get message attachments

Get attachments on message by calling the Attachments property. To get a particular attachment, specify the attachment ID as the index of the Attachments collection or use the GetById method.

Note Attachment collections support query expressions such as Select, OrderBy, and Take.

This example calls the method that creates the Outlook Services client. The .NET code assumes you already got the message ID.

var outlookClient = await CreateOutlookClientAsync("Mail");
var messages = await outlookClient.Me.Folders["Inbox"].Messages
  .Where(m => m.HasAttachments == true)
  .Expand(m => m.Attachments)
  .Take(10)
  .ExecuteAsync();

foreach (var message in messages.CurrentPage)
{
  var attachments = message.Attachments.CurrentPage;
  System.Diagnostics.Debug.WriteLine("Message '{0}' contains '{1}' attachment(s).",
    message.Subject,
    attachments.Count);

  foreach (var attachment in attachments)
  {
    System.Diagnostics.Debug.WriteLine("*    '{0}' ({1} KB)",
      attachment.Name,
      attachment.Size);
  }
}
outlookClient.me.folders.getFolder('Inbox').messages.getMessages().filter('HasAttachments eq true').fetchAll(10).then(function (result) {
    result.forEach(function (message) {
        message.attachments.getAttachments().fetchAll(100).then(function (attachmentResult) {
            console.log('Message "' + message.subject + '" contains ' + attachmentResult.length + ' attachment(s)');
            attachmentResult.forEach(function (attachment) {
                console.log('*    "' + attachment.name + '" (' + attachment.size + ' KB)');
            });
        });
    }, function (error) {
        console.log(error);
    });
}, function (error) {
    console.log(error);
});

Get folders

Get the top-level folders in the mailbox by using the Me.Folders shortcut property. To get the folders from a specific folder, use its ChildFolders property. You can use the following well-known folder names instead of the ID for the corresponding folder: Inbox, SentItems, Drafts, DeletedItems.

Example: outlookClient.Me.Folders["Drafts"].ChildFolders.ExecuteAsync()

To get a particular folder, specify the folder ID as the index of the Folders collection or use the GetById method.

Note Folder collections support query expressions such as Select, OrderBy, and Take.

This example calls the method that gets the Outlook Services client.

var outlookClient = await CreateOutlookClientAsync("Mail");
var mailFolders = await outlookClient.Me.Folders
  .Take(10)
  .ExecuteAsync();

foreach(var mailFolder in mailFolders.CurrentPage)
{
  System.Diagnostics.Debug.WriteLine("Mail folder '{0}'.", mailFolder.DisplayName);
}
outlookClient.me.folders.getFolders().fetchAll(100).then(function (result) {
    result.forEach(function (folder) {
        console.log('Folder "' + folder.displayName + '"');
    });
}, function (error) {
    console.log(error);
});

Create folders

Create a Folder object and pass it to the AddFolderAsync method on the destination folder's ChildFolders collection.

This example assumes you already got the Outlook Services client and got the folder ID of the parent folder.

Folder newFolder = new Folder
{
    DisplayName = "Private"
};
await outlookClient.Me.Folders["Inbox"].ChildFolders.AddFolderAsync(newFolder);

// Get the ID of the new folder.
string folderId = newFolder.Id;

Update folders

Change a folder name. DisplayName is the only writeable property for a folder.

This example assumes you already got the Outlook Services client and got the folder ID.

IFolder folder = await outlookClient.Me.Folders[folderId].ExecuteAsync();
folder.DisplayName = "Personal";
await folder.UpdateAsync();

// Get the updated property.
string updatedName = folder.DisplayName;

You can define multiple updates client-side and send the requests all at once (batch them) by using the following pattern:

  1. Call UpdateAsync(true) for each entity you want to update. Specifying true registers the updates locally on the client but doesn't post them to the server.
  2. Call outlookClient.Context.SaveChangesAsync() to post all updates that are registered locally.

Delete folders

Delete a folder by calling DeleteAsync.

This example assumes you already got the Outlook Services client and got the folder ID.

IFolder folder = await outlookClient.Me.Folders[folderId].ExecuteAsync();
await folder.DeleteAsync();

Move or copy folders

Move or copy a folder by passing the ID of the destination folder to the MoveAsync or CopyAsync method.

This example assumes you already got the Outlook Services client and got the folder ID of the folder to move and the destination folder.

IFolder folder = await outlookClient.Me.Folders[folderId].ExecuteAsync();
await folder.MoveAsync("AAMkADE3N...");
IFolder folder = await outlookClient.Me.Folders[folderId].ExecuteAsync();
await folder.CopyAsync("Inbox");

Additional resources