Getting Started with Cloud Mail
Requirements: Cloud Mail
Cloud Mail provides a suite of easy-to-use mail management components. Quickly and securely send, receive and manage mail using popular cloud services such as Office365 (Graph API), Amazon SES, and Gmail.
If it is desired to use SMTP, IMAP, or POP instead take a look here for more information on combining OAuth with our other mail components.
Contents
Amazon SES
The AmazonSES component provides a simple interface for Amazon's "Simple Email Service". The component supports sending both plain-text or HTML emails, adding, listing, and removing identities, verifying domains and emails and gathering administrative data.
Authentication
After signing up for Amazon SES, you will be provided an "Access Key" and a "Secret Key". Before making any requests to Amazon, you must set these values to their corresponding properties like below.
AmazonSES.AccessKey = "my access key";
AmazonSES.SecretKey = "my secret key";
Sending Messages
You can send a message using the component's Send method. Before calling the method set MessageHTML or MessageText along with From, Subject, and SendTo. You may also add attachments by calling the AddAttachment method providing the path to the file that is stored locally on the machine.
Sending a message with attachments:
AmazonSES.AccessKey = "my access key";
AmazonSES.SecretKey = "my secret key";
AmazonSES.AddAttachment("C:\file1.zip");
AmazonSES.From = "verified.email@host.com";
AmazonSES.SendTo = "recipient@mail.com";
AmazonSES.Subject = "Test SES Email";
AmazonSES.MessageHTML = "Hello World!";
AmazonSES.Send();
Gmail
The Gmail component provides an easy to use interface to Gmail using Google's REST API. The Gmail component supports sending and retrieving messages, creating or deleting labels, and other functionality.
OAuth Authentication
Before using the component, an OAuth token must be provided through the Authorization property. The OAuth component included in the toolkit can be used to assist in this process.
By design, user-interaction is required to fetch an OAuth authorization string the first time. A user must be directed to a URL where they will authenticate and grant access to the connecting application. The user is then redirected back to the application along with a code which will be exchanged for an authorization string by the OAuth component. The authorization string is then used in requests to the cloud service.
The authorization string is valid only for a limited period of time; however a parameter can be included in the initial authorization to request a refresh token which can be used without user interaction to update the authorization token. To add an additional parameter the AddParam method can be used. In the below example, the "access_type" parameter is set to "offline".
Fetching an OAuth authorization string using the OAuth component:
OAuth oauth = new OAuth();
oauth.ClientId = "CLIENT_ID";
oauth.ClientSecret = "CLIENT_SECRET";
oauth.ServerAuthURL = "https://accounts.google.com/o/oauth2/auth";
oauth.ServerTokenURL = "https://accounts.google.com/o/oauth2/token";
oauth.AuthorizationScope = "https://mail.google.com/";
oauth.GrantType = OAuthGrantTypes.ogtAuthorizationCode;
oauth.AddParam("access_type", "offline");
gmail.Authorization = oauth.GetAuthorization();
Sending Messages
There are two methods for sending messages using the Gmail 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:
gmail.MessageSubject = "Subject Text";
gmail.MessageBodyContentType = "TEXT";
gmail.MessageBodyContent = "Body Text";
gmail.MessageTo = "example@email.com";
gmail.SendMail();
Sending a Message with SendDraft:
gmail.MessageSubject = "I am sending an email.";
gmail.MessageBodyContentType = "TEXT";
gmail.MessageBodyContent = "Just wanted to let you know.";
gmail.MessageTo = "reader@tautology.org";
string messageId = "";
gmail.CreateDraft();
messageId = gmail.MessageInfo[0].Id;
gmail.SendDraft(messageId);
Retrieving Messages
Information about messages fetched by the component can be accessed through the MessageInfo collection. MessageInfo is populated when the ListMessages, RetrieveMessageInfo, ListDrafts, or Search methods are called.
The ListMessages methods will list the messages in the mailbox. The filter and threadId parameters can be used to retrieve a subset of the message or both can be left empty to retrieve all the messages.
Listing Messages in the Mailbox:
// List all messages. The filter and threadId parameters are empty.
gmail.ListMessages("", "");
By default, the component will fetch one page of 100 messages when ListMessages is called. If additional messages remain in the mailbox, the NextPageToken property will be populated. If ListMessages is then called again on the same filter and threadId the next page of messages will be fetched. The example below populates MessageInfo with all the messages in the mailbox.
Listing all Pages of Messages in the Mailbox:
do {
// List all messages. The filter and threadId parameters are empty.
gmail.ListMessages("", "");
} while (gmail.NextPageToken.Length > 0);
The message page size may also be changed by using the MessagePageSize configuration setting.
The component also provides methods to retrieve specific parts of any given message using the RetrieveMessage, RetrieveMessageHeaders, and RetrieveMessageRaw methods. Each method takes a messageId parameter which can be found from the MessageInfo collection.
Printing Content of all Messages in the Mailbox:
do {
gmail.ListMessages("", "");
} while (gmail.NextPageToken.Length > 0);
foreach (GLMessageInfo messageInfo in gmail.MessageInfo)
{
gmail.RetrieveMessage(messageInfo.Id);
foreach (GLMessagePart part in gmail.MessageParts)
{
if (part.ContentType.Equals("text/plain"))
Console.WriteLine(part.Data);
}
}
Office365
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.
OAuth Authentication
Before using the component, an OAuth token must be provided through the Authorization property. The OAuth component included in the toolkit can be used to assist in this process.
By design, user-interaction is required to fetch an OAuth authorization string the first time. A user must be directed to a URL where they will authenticate and grant access to the connecting application. The user is then redirected back to the application along with a code which will be exchanged for an authorization string by the OAuth component. The authorization string is then used in requests to the cloud service.
The authorization string is valid only for a limited period of time; however a parameter can be included in the initial authorization to request a refresh token which can be used without user interaction to update the authorization token.
Fetching an OAuth authorization string using the OAuth component:
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 = "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 = "Subject Text";
office365.MessageImportance = "Low";
office365.MessageBodyContentType = "TEXT";
office365.MessageBodyContent = "Body Text";
office365.MessageTo = "example@email.com";
office365.SendMail(true);
Sending a Message with SendDraft:
office365.MessageSubject = "Subject Text";
office365.MessageImportance = "Low";
office365.MessageBodyContentType = "TEXT";
office365.MessageBodyContent = "Body Text";
office365.MessageTo = "email@example.com";
string messageId = "";
office365.CreateDraft(0, "");
messageId = office365.MessageInfo[0].Id;
office365.SendDraft(messageId);
There are also methods for replying or forwarding messages using the Office365 component. The Reply, ReplyAll, and Forward methods will send a reply or forward directly. Similarly, you can create a reply or forward draft using the CreateDraft method and then send an existing draft using the SendDraft method. Unlike creating a new message, only the direct methods use the Message properties (MessageSubject, MessageBodyContent, MessageCc, etc.). When using CreateDraft, the draft must first be made, then it should be updated using the MessageInfo collection and Update method.
Sending a Reply with SendDraft
// Create the reply draft
string originalMessageId = "Message ID";
office365.CreateDraft(1, originalMessageId);
// Set the new draft MessageInfo fields with desired options
office365.MessageInfo[0].To = "email@example.com";
office365.MessageInfo[0].Subject = "Subject Text";
office365.MessageInfo[0].BodyContentType = "TEXT";
office365.MessageInfo[0].BodyContent = "Body Text";
// Update the draft
office365.Update(office365.MessageInfo[0].Id);
// Send the draft
office365.SendDraft(office365.MessageInfo[0].Id);
Retrieving Messages
Information about messages fetched by the component can be accessed through the MessageInfo collection. MessageInfo is populated when the ListMessages, RetrieveMessage, 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 support@nsoftware.com.