Using CloudMailer to Send Emails

Requirements: Cloud Mail

Cloud Mail provides a suite of easy-to-use mail management components. This article covers sending emails with Amazon's Simple Email Service (SES), Google's Gmail, and Microsoft's Office 365 (Graph API) using the CloudMailer component. For more about Cloud Mail's capabilities as a whole, please see our Getting Started with Cloud Mail article.

The CloudMailer component provides a single interface for sending mail through any of the supported service providers. To get started, select the service provider with the ServiceProvider property, and set the Account property to valid credentials for that provider. The message is then specified with properties such as SendTo, Subject, and MessageHTML, and sent with the Send method.

CloudMailer cloudmailer = new CloudMailer(); // Possible values are spAmazonSES (the default), spGmail, and spOffice365. cloudmailer.ServiceProvider = CloudMailerServiceProviders.spGmail;

Contents

• Authentication
  • Amazon SES
  • Gmail and Office 365
• Sending Emails
  • Basic Message Aspects
  • Additional Message Options
  • Adding Attachments
  • Queuing Messages

Authentication

All supported service providers require authentication before they can be used to send messages. The credentials for each provider are set in the Account property.

Amazon SES

After signing up for Amazon SES, an access key and a secret key are provided. These values must be supplied to the component through the Key and Secret fields of the Account property.

cloudmailer.ServiceProvider = CloudMailerServiceProviders.spAmazonSES; cloudmailer.Account.Key = "MY_ACCESS_KEY"; cloudmailer.Account.Secret = "MY_SECRET_KEY"; // Optionally, select a region other than the default (us-east-1). cloudmailer.Config("Region=eu-west-1");

Note that in versions prior to 2026, these fields were named AmazonAccessKey and AmazonSecretKey.

Gmail and Office 365

Sending emails through Gmail and Office 365 requires OAuth authorization. The component supports two different ways to complete this process.

The simplest approach is to use the component's built-in OAuth support. Configure the OAuth property, and then call the Authorize method. Since the OAuth property applies to the currently selected service provider, the ServiceProvider property must be set first; otherwise, the values set in the OAuth property are not used.

cloudmailer.ServiceProvider = CloudMailerServiceProviders.spGmail; cloudmailer.OAuth.ClientProfile = CloudOAuthClientProfiles.cocpApplication; cloudmailer.OAuth.GrantType = OAuthSettingsGrantTypes.cogtAuthorizationCode; cloudmailer.OAuth.ClientId = "CLIENT_ID"; cloudmailer.OAuth.ClientSecret = "CLIENT_SECRET"; cloudmailer.Authorize();

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 LaunchBrowser event fires before the browser is launched, and can be used to customize or suppress launching the browser.

When Gmail is the active service provider, the OAuth property fields contain the following defaults:

When Office 365 is the active service provider, the OAuth property fields contain the following defaults:

For Office 365 applications that are registered as single tenant, or that use the client credentials grant type, the tenant ID must be used in place of common in the URLs above.

Alternatively, a valid OAuth token obtained by other means can be provided to the component through the Authorization field of the Account property. The separate OAuth component included in the toolkit can be used to obtain this token. A basic example for Gmail is shown below. The "access_type" parameter is set to "offline" to request a refresh token from Google.

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"); cloudmailer.Account.Authorization = oauth.GetAuthorization();

A similar example for Office 365 is shown below. Including the "offline_access" scope requests a refresh token from Microsoft.

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 mail.send mailboxsettings.readwrite"; oauth.GrantType = OAuthGrantTypes.ogtAuthorizationCode; cloudmailer.Account.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.

Sending Emails

The process of sending messages with the component is the same regardless of the service provider, which minimizes the amount of code that needs to be written and maintained to send mail across multiple service providers.

Basic Message Aspects

The component sends the message provided in the MessageHTML and MessageText properties. The MessageHTML property contains the HTML version of the message, while the MessageText property contains the corresponding plaintext version. When MessageHTML is set, the component automatically computes a plaintext version of the message and stores it in MessageText. This plaintext version may be overridden if desired.

The recipients are specified by the SendTo, Cc, and BCc properties, and the message subject is specified by the Subject property.

Once all the appropriate properties have been set, call the Send method to send the message to its recipients.

cloudmailer.From = "me@gmail.com"; cloudmailer.SendTo = "recipient@example.com"; cloudmailer.Subject = "My Subject"; cloudmailer.MessageHTML = "<b>This is the message body.</b>"; cloudmailer.Send();

Additional Message Options

Several optional properties can be used to further customize the message:

• ReplyTo specifies the address to which replies should be sent, if different from the From address.
• Importance specifies the importance of the message (e.g., CloudMailerImportances.miHigh).
• ReadReceiptTo specifies an address that should receive a read receipt.
• DeliveryNotificationTo specifies an address that should receive a delivery notification.

Note that Importance and ReadReceiptTo have no effect on messages sent to Gmail recipient addresses, and DeliveryNotificationTo has no effect when Gmail is the service provider.

cloudmailer.ReplyTo = "support@example.com"; cloudmailer.Importance = CloudMailerImportances.miHigh; cloudmailer.ReadReceiptTo = "me@example.com"; 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.

cloudmailer.AddAttachment("C:\\reports\\file1.zip"); cloudmailer.AddAttachment("C:\\reports\\file2.zip"); cloudmailer.Send();

Alternatively, attachments can be added directly to the Attachments collection. The Attachments property is a collection of FileAttachment objects, an included type that describes the file being attached.

cloudmailer.Attachments.Add(new FileAttachment("report.txt", "C:\\reports\\file.txt"));

To supply the data for an attachment through a stream instead, use the SetAttachmentInStream method. The first parameter is the index of the attachment in the Attachments collection whose data the stream will supply.

cloudmailer.Attachments.Add(new FileAttachment("attachment1.txt")); cloudmailer.SetAttachmentInStream(0, new FileStream("C:\\reports\\attachment1.txt", FileMode.Open));

Queuing Messages

Instead of sending a message immediately, the Queue method can be used to save the message to a queue directory for sending later. The directory must already exist, and the method returns the name of the queue file it created, which has a .queued extension.

The ProcessQueue method sends all of the messages that have been queued in the specified directory. While a message is being sent, its file extension is changed to .sending. If a message fails to send, its file extension is changed to .failed. Messages that are sent successfully are deleted from the queue directory, unless the KeepQueue configuration setting is enabled, in which case their file extension is changed to .sent.

// Queue two messages. cloudmailer.SendTo = "recipient@example.com"; cloudmailer.Subject = "First Message"; cloudmailer.MessageText = "This is the first message."; cloudmailer.Queue("C:\\mailqueue"); cloudmailer.Subject = "Second Message"; cloudmailer.MessageText = "This is the second message."; cloudmailer.Queue("C:\\mailqueue"); // Later, send all of the queued messages. cloudmailer.ProcessQueue("C:\\mailqueue");