Organizing an Office 365 Mailbox with Cloud Mail

Requirements: Cloud Mail

Cloud Mail provides a suite of easy-to-use mail and contact management components. This article covers organizing an Office 365 mailbox with the Office365 component, including listing, creating, renaming, moving, copying, and deleting mail folders, as well as moving and copying messages between folders. For sending mail and other general usage, please see our Getting Started with Cloud Mail article for more information.

Contents

• Authorization
• Listing Folders
• Creating, Renaming, and Deleting Folders
• Moving and Copying Folders
• Listing Messages in a Folder
• Moving and Copying Messages

Authorization

Before using the Office365 component, it must be authorized via OAuth. The simplest approach is to configure the built-in OAuth property and call the Authorize method. The component's default scopes already include read and write access to mail.

By design, user interaction is required the first time the component is authorized. When the Authorize method is called, the component starts an embedded web server and launches a browser so the user can sign in and grant access to the application. Once access is granted, the service redirects the browser back to the embedded web server, and the component automatically exchanges the authorization code it receives for an access token. The component then uses the access token in its requests, and automatically obtains a new one when it expires.

Office365 office365 = new Office365(); office365.OAuth.ClientProfile = CloudOAuthClientProfiles.cocpApplication; office365.OAuth.GrantType = OAuthSettingsGrantTypes.cogtAuthorizationCode; office365.OAuth.ClientId = "CLIENT_ID"; office365.OAuth.ClientSecret = "CLIENT_SECRET"; office365.Authorize();

Alternatively, the separate OAuth component included in the toolkit can be used to obtain an authorization string, which is then assigned to the Authorization property. The authorization string is valid only for a limited period of time, but including the "offline_access" scope requests a refresh token, which can be used without user interaction to update the authorization string.

OAuth oauth = new OAuth(); oauth.ClientId = "CLIENT_ID"; oauth.ClientSecret = "CLIENT_SECRET"; oauth.ServerAuthURL = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"; oauth.ServerTokenURL = "https://login.microsoftonline.com/common/oauth2/v2.0/token"; oauth.AuthorizationScope = "offline_access user.read mail.readwrite"; oauth.GrantType = OAuthGrantTypes.ogtAuthorizationCode; office365.Authorization = oauth.GetAuthorization();

For more information about OAuth authorization, including persisting refresh tokens, web applications, and unattended applications, please see our OAuth Authorization in /n software Cloud Products article.

Listing Folders

The ListFolders method lists the folders found in the specified parent folder and populates the Folders collection. Passing an empty string lists the folders in the root of the mailbox, such as Inbox, Drafts, and Sent Items. The FolderList event will also fire once for each folder.

If the number of folders exceeds the page size (100 by default, controlled by the FolderPageSize configuration setting), the ListFoldersMarker property will be populated. Calling ListFolders again retrieves the next page, and the results are added to the end of the Folders collection.

Each folder in the collection exposes its Id, DisplayName, ParentFolderId, ChildFolderCount, TotalItemCount, and UnreadItemCount. Most other methods reference folders by their ID, so a common first step is to look up the ID of a folder by its display name.

// List all folders in the root of the mailbox. do { office365.ListFolders(""); } while (office365.ListFoldersMarker.Length > 0); // Find the Inbox and print some information about each folder. string inboxId = ""; foreach (OLFolder folder in office365.Folders) { Console.WriteLine(folder.DisplayName + ": " + folder.TotalItemCount + " messages (" + folder.UnreadItemCount + " unread)"); if (folder.DisplayName.Equals("Inbox")) inboxId = folder.Id; }

Note that folder display names depend on the mailbox's language settings, so a folder such as Inbox may have a different display name in some mailboxes.

To list the subfolders of a folder, pass the parent folder's ID to ListFolders. The ChildFolderCount field indicates whether a folder has any subfolders.

// List the subfolders of the Inbox. do { office365.ListFolders(inboxId); } while (office365.ListFoldersMarker.Length > 0); foreach (OLFolder folder in office365.Folders) { Console.WriteLine(folder.DisplayName); }

A single folder can also be retrieved by its ID using the GetFolder method. The retrieved folder is inserted at the beginning (index 0) of the Folders collection.

Creating, Renaming, and Deleting Folders

The CreateFolder method creates a new folder. The first parameter is the name of the new folder, and the second is the ID of the parent folder. To create a folder in the root of the mailbox, pass an empty string as the parent folder ID. The new folder is inserted at the beginning (index 0) of the Folders collection, so its ID can be read immediately after the method returns.

// Create a folder in the root of the mailbox. office365.CreateFolder("Projects", ""); string projectsId = office365.Folders[0].Id; // Create a subfolder within the new folder. office365.CreateFolder("2026", projectsId); string subfolderId = office365.Folders[0].Id;

The RenameFolder method changes the display name of an existing folder, and the DeleteFolder method deletes a folder.

// Rename a folder. office365.RenameFolder(subfolderId, "Archive 2026"); // Delete a folder. office365.DeleteFolder(subfolderId);

Note that DeleteFolder does not remove the folder from the Folders collection. Call ListFolders again to refresh the collection after deleting folders.

Moving and Copying Folders

The MoveFolder method moves a folder (along with its contents) to a new parent folder, and the CopyFolder method copies a folder to a new parent folder. Two folders with the same name cannot exist under the same parent folder. Since CopyFolder does not change the name of the folder, a folder cannot be copied into its own parent folder.

// Create a destination folder and a folder to copy. office365.CreateFolder("Completed", ""); string completedId = office365.Folders[0].Id; office365.CreateFolder("Templates", ""); string templatesId = office365.Folders[0].Id; // Move the "Projects" folder into the "Completed" folder. office365.MoveFolder(projectsId, completedId); // Copy the "Templates" folder into the "Completed" folder. office365.CopyFolder(templatesId, completedId);

Neither method updates the Folders collection. Call ListFolders again to see the folders in their new location.

Listing Messages in a Folder

The ListMessages method lists the messages in the specified folder and populates the MessageInfo collection. The MessageList event will also fire once for each message.

The second parameter is an optional filter which follows the OData protocol syntax, and may be used to retrieve only a specific subset of messages. Pass an empty string to retrieve all messages in the folder.

If the number of messages exceeds the page size (100 by default, controlled by the MessagePageSize configuration setting), the ListMessagesMarker property will be populated. Calling ListMessages again with the same folder ID retrieves the next page, and the results are added to the end of the MessageInfo collection.

// List all unread messages in the Inbox. do { office365.ListMessages(inboxId, "isRead eq false"); } while (office365.ListMessagesMarker.Length > 0); for (int i = 0; i < office365.MessageInfo.Count; i++) { Console.WriteLine(office365.MessageInfo[i].Subject + " from " + office365.MessageInfo[i].From); }

Some other useful filters include:

• from/emailAddress/address eq 'someone@example.com' to list messages from a specific sender.
• hasAttachments eq true to list messages that have attachments.
• receivedDateTime lt 2026-01-01T00:00:00Z to list messages received before a specific date.

Filters may be combined using and and or, for example isRead eq false and hasAttachments eq true.

Moving and Copying Messages

The MoveMessage method moves a message to another folder, and the Copy method copies a message to another folder. Both methods take the ID of the message as the first parameter and the ID of the destination folder as the second parameter.

After either method returns, the moved or copied message is inserted at the beginning (index 0) of the MessageInfo collection. The ID of a message may change when it is moved, so the entry at index 0 should be used for any further operations on the message. Note that MoveMessage does not remove the original entry from the MessageInfo collection.

// Move a message from the Inbox to the "Projects" folder. office365.ListMessages(inboxId, ""); string messageId = office365.MessageInfo[0].Id; office365.MoveMessage(messageId, projectsId); // The moved message is now at index 0 of the MessageInfo collection. string movedMessageId = office365.MessageInfo[0].Id; // Copy the moved message back to the Inbox. office365.Copy(movedMessageId, inboxId); string copiedMessageId = office365.MessageInfo[0].Id;

Since MoveMessage and Copy insert entries into the MessageInfo collection, the collection should not be iterated by index while messages are being moved. Instead, the IDs of the messages should be gathered first, and then moved. The example below moves every read message received before 2026 from the Inbox into a new "Archive 2025" folder.

// Find the Inbox. do { office365.ListFolders(""); } while (office365.ListFoldersMarker.Length > 0); string inboxId = ""; foreach (OLFolder folder in office365.Folders) { if (folder.DisplayName.Equals("Inbox")) inboxId = folder.Id; } // Create the destination folder. office365.CreateFolder("Archive 2025", ""); string archiveId = office365.Folders[0].Id; // Gather the IDs of all read messages received before 2026. do { office365.ListMessages(inboxId, "isRead eq true and receivedDateTime lt 2026-01-01T00:00:00Z"); } while (office365.ListMessagesMarker.Length > 0); List<string> messageIds = new List<string>(); for (int i = 0; i < office365.MessageInfo.Count; i++) { messageIds.Add(office365.MessageInfo[i].Id); } // Move each message into the archive folder. foreach (string id in messageIds) { office365.MoveMessage(id, archiveId); } Console.WriteLine("Archived " + messageIds.Count + " messages.");