Getting Started with Office365

Requirements: IPWorks Mail

The Office365 component provides an easy to use interface for Office365 using Microsoft's Graph API. To use the component, first set the Authorization property to a valid OAuth token.

The Office365 component supports sending or creating new messages; retrieving, moving, or copying existing messages; creating, deleting, or copying folders; and several other functionalities supported by the Microsoft Graph API.

Contents

OAuth Authentication

Before using the component, an OAuth token must be provided through the Authorization property.

By design, user-interaction is required to fetch an OAuth token for the first time. A user's OAuth credentials are sent to an OAuth server, where the user must manually authenticate. If the authentication succeeds, this data is encoded in a token and that token is returned to the original application (in this case, the Office365 component). The component will then use this token to authenticate with the Office365 server.

These authentication tokens are valid for a limited period of time; however, the OAuth server also returns a refresh token that can be used to refresh expired authentication tokens.

Fetching an OAuth token using the OAuth component:

Oauth oauth = new Oauth();
 
oauth.ClientId = "3c65828c-6376-4286-91b5-2381c3904a97"; 
oauth.ClientSecret = "mkk2a2M-B5TQI7o5p_N0fR-CHYVn7e3yH~";
oauth.ServerAuthURL = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
oauth.ServerTokenURL = "https://login.microsoftonline.com/common/oauth2/v2.0/token";
oauth.AuthorizationScope = "user.read mail.readwrite mail.send mailboxsettings.readwrite";
oauth.GrantType = OauthGrantTypes.ogtAuthorizationCode;
 
office365.Authorization. = oauth.GetAuthorization();

Sending Messages

There are two methods for sending messages using the Office365 component. The SendMail method will send a message directly. Alternatively, you can create a message draft and then send an existing draft using the SendDraft method. In both cases the properties of the new message are assigned through the Message properties (MessageSubject, MessageBodyContent, MessageCc, etc.).

Sending a message with SendMail:

office365.MessageSubject = "I saw a Tree";
office365.MessageImportance = "High";
office365.MessageBodyContentType = "TEXT";
office365.MessageBodyContent = "It was in my back yard initially. It was still there when I last checked.";
office365.MessageTo = "TreeLookOut@gmail.com";
 
office365.SendMail(True);

Sending a Message with SendDraft:

office365.MessageSubject = "I am sending an email.";
office365.MessageImportance = "Low";
office365.MessageBodyContentType = "TEXT";
office365.MessageBodyContent = "Just wanted to let you know.";
office365.MessageTo = "reader@tautology.org";

string messageId = "";
office365.CreateDraft(0, "");
messageId = office365.MessageInfo[0].Id;

office365.SendDraft(messageId)

Retrieving Messages

Information about messages fetched by the component can be accessed through the MessageInfo collection. MessageInfo is populated when the ListMessages, GetMessage, Search, or ListChanges methods are called.

The ListMessages and ListChanges methods will respectively list the messages or changed messages in a folder specified by a folderId. To get the ID of a folder, folders can be traversed and read using the ListFolders method and the Folders collection.

Listing Messages in a Folder:

// Get the folder ID
string folderId = "";

office365.ListFolders(""); // Lists the root child folders.

for (int i = 0; i < office365.Folders.Count; i++)
{
  if (office365.Folders[i].DisplayName.Equals("SpecificFolderName"))
  {
    folderId = office365.Folders[i].Id;
    break;
  }
}

// List folder messages
office365.ListMessages(folderId, "");

By default, the component will fetch one page of 100 messages when ListMessages is called. If additional messages remain in the folder, the ListMessagesMarker property will be populated. If ListMessages is then called again on the same folder the next page of messages will be fetched. The example below populates MessageInfo with all the messages in a particular folder.

do {
  office365.ListMessages(folderId);
} while (office365.ListMessagesMarker.Length > 0);

The message page size may also be changed by using the MessagePageSize configuration setting.

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.