Using CloudMailer to Send Emails
Requirements: Cloud Mail
Cloud Mail provides a suite of easy-to-use mail management components. This article covers sending simple emails with Amazon's Simple Email Service (SES), Google's Gmail, and Microsoft's Office365 (Graph API) using the CloudMailer component. For more about Cloud Mail's capabilities as a whole, please see Getting Started with Cloud Mail.
To get started using the component, first choose the desired service provider with the ServiceProvider property. Then, set the Account property to valid credentials for the chosen provider. Message details can then be specified with properties including (but not limited to) MessageHTML, Subject, and SendTo to craft the email before sending with the Send method.
Contents
Authentication
All supported service providers require some manner of authentication to be completed and set in the Account property before they can be used to send messages.
Amazon SES
After signing up for Amazon SES, you will be provided an "Access Key" and a "Secret Key". These values must be provided to the component through the AmazonAccessKey and AmazonSecretKey fields of the Account property, respectively, as shown below.
cloudmailer.Account.AmazonAccessKey = "my access key";
cloudmailer.Account.AmazonSecretKey = "my secret key";
Gmail and Office365
OAuth must be performed before sending emails via Gmail and Office365 with the component. The component supports two different ways to complete this process.
One option is to provide a valid OAuth token to the component through the Authorization field of the Account property. The OAuth component included in the toolkit can be used to assist with obtaining this token. A basic example of how this can be done for Gmail is shown below.
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/";
cloudmailer.Account.Authorization = oauth.GetAuthorization();
A similar example for Office365 is also provided below.
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";
cloudmailer.Account.Authorization = oauth.GetAuthorization();
Alternatively, the component's OAuth property can be used to set the appropriate fields for the desired ClientProfile and GrantType. When Gmail is the active service provider, the OAuth property fields contain the following defaults:
| Field | Value |
|---|---|
| ServerAuthURL | "https://accounts.google.com/o/oauth2/auth" |
| ServerTokenURL | "https://accounts.google.com/o/oauth2/token" |
| AuthorizationScope | "https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/gmail.compose https://mail.google.com/" |
When Office365 is the active service provider, the OAuth property fields contain the following defaults:
| Field | Value |
|---|---|
| ServerAuthURL | "https://login.microsoftonline.com/common/oauth2/v2.0/authorize" |
| ServerTokenURL | "https://login.microsoftonline.com/common/oauth2/v2.0/token" |
| AuthorizationScope | "offline_access mail.readwrite mail.send user.read" |
The Authorize method can then be called to perform the OAuth process as shown below.
cloudmailer.OAuth.ClientId = "CLIENT_ID";
cloudmailer.OAuth.ClientSecret = "CLIENT_SECRET";
cloudmailer.Authorize();
Sending Emails
The process of sending messages with the component is the same regardless of service provider, minimizing the amount of code that needs to be written and maintained to send mail across multiple service providers.
Basic Message Aspects
The component sends a message that is provided in the MessageHTML and MessageText properties. The MessageHTML property contains the HTML version of the message, while the corresponding plaintext version is provided in the MessageText property. When MessageHTML is set, the component automatically computes a plaintext version of the text and puts it into MessageText. This default text may be overridden if desired, as well.
The recipients are specified by the SendTo, Cc, and BCc properties, and the message subject is settable in the Subject property.
Once all the appropriate properties have been set, the Send method can be called to send the message to its intended recipient(s). A basic example is shown below.
cloudmailer.From = "me@gmail.com";
cloudmailer.SendTo = "recipient@server.com";
cloudmailer.Subject = "My Subject";
cloudmailer.MessageHTML = "This is the message body.";
cloudmailer.Send();
Adding Attachments
The component provides several different ways to add attachments to messages.
The AddAttachment method can be supplied with the path to a local file to include as an attachment as shown below.
cloudmailer.AddAttachment("C:\file1.zip");
cloudmailer.AddAttachment("C:\file2.zip");
cloudmailer.Send();
Alternatively, the Attachments property can be modified directly to include attachments. An example of attaching a local file is shown below.
cloudmailer.Attachments.Add(new FileAttachment("name", "C:\file.txt"));
To add an attachment as a stream instead, the SetAttachmentInStream method can be used as shown.
cloudmailer.Attachments.Add(new FileAttachment("attachment1.txt"));
cloudmailer.SetAttachmentInStream(0, new FileStream("C:\attachment1.txt", FileMode.Open));
We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at support@nsoftware.com.