SendEmail

The SendEmail function sends an email that uses the email sender service. You can send emails from within a policy to send email notification to administrators and users when a certain event or combination of events occur.

Important: Netcool®/Impact does not provide a built-in mail server. Before you can send email, you must make sure that an SMTP server is available in your environment. The Netcool/Impact email sender service must also be running before a policy can successfully send email.

To send email, you call the SendEmail function and pass the following information as input parameters:

The email address of the recipient.
The subject line text for the email.
The body content of the email.
The name of the email sender.

You can send an email by passing a data item whose Email member variable contains a valid email address. This field must be named Email. You cannot use a data item that has another field that contains email addresses.

The SendEmail function uses UTF-8 encoding of the operating system by default. You can customize the encoding by including the following syntax before you run the call SendEmail:

EncodingChar = "<type of charset>";

// Example: use windows-1251 encoding for the email
EncodingChar = "windows-1251";

Syntax

The SendEmail function has the following syntax:

SendEmail(User, Address, Subject, Message, Sender, ExecuteOnQueue, [Attachment], [CallProperties])

Parameters

The SendEmail function has the following parameters.

Table 1. SendEmail function parameters
Parameter	Format	Description
`User`	Data item	Data item of any data type whose `Email` field contains the email address of the recipient.
`Address`	String or a context object	Email address for the recipient of the email. If this parameter is specified, the `User` parameter is ignored. You can specify the To, CC, and BCC fields of the email separately. Multiple email addresses must be separated by a comma (,).
`Subject`	String	Subject for the message.
`Message`	String	Message body for the email.
`Sender`	String	Email address for the sender for the email.
`ExecuteOnQueue`	Boolean	Specifies whether to place the outgoing message in the queue that is governed by the command execution manager service. If you specify `true`, the message is placed in the queue and sent asynchronously by this service. If you specify `false`, the message is sent directly by Netcool/Impact. In this case, the policy engine waits for the message to be sent successfully before it processes any subsequent instructions.
`Attachment`	String	Full file path name to send as an attachment to the email. Optional. Note: When using the `SendEmail` functionality on Windows, use a single forward slash character instead of double back slash characters to specify the position of a file.
`Properties`	Object	Call properties to set additional parameters such as enable HTML or authentication. Optional.

The following table shows the full set of optional properties that you can use with the Properties parameter.

Table 2. Optional properties for the *Properties* parameter.
Parameter	Format	Description
`EmailContentType`	String	Set the value of the `Content-Type` header for the text portions of the email. The default value is `text/plain`.
`UseAuth`	Boolean	Enable authentication if the email server requires it for access.
`AuthUser`	String	The user name used for authentication.
`AuthPassword`	String	The password used for authentication. The password can be in plaintext or encrypted with `Encrypt()` or `nci_crypt`.
`DecryptPassword`	Boolean	If set to `true`, the `SendEmail` function must decrypt the password before using it.
`EmailImages`	Object	An object which contains one or more image paths. These images can be embedded into HTML emails.
`DebugEnabled`	Boolean	If set to `true`, the `SendEmail` function will generate additional debug logging in the web server log.
`ContentTypePlainText`	Boolean	By default, emails are sent as multipart MIME messages. If this property is set to `true`, emails will be sent as plain text emails without any multipart container.
`ContentTransferEncoding`	String	Set the value of the `Content-Transfer-Encoding` header for the text portions of the email.

Example

The following example shows how to send an email from a policy that uses the email address of the recipient.

// Call SendEmail and pass the address, subject and message text
// as input parameters
					
Address = "srodriguez@example.com";
Subject = "Netcool/Impact Notification";
Message = EventContainer.Node + " has reported the following error condition: "
+ EventContainer.Summary;
Sender = "impact";
ExecuteOnQueue = false;
Attachment = null;
					
SendEmail(null, Address, Subject, Message, Sender, ExecuteOnQueue, Attachment);

Here is an example of using the SendEmail function if the Address parameter is a context object:

Addresses = NewObject();
Addresses.To = "to@example.com";
Addresses.Cc = "cc1@example.com,cc2@example.com";
Addresses.Bcc = "bcc@example.com";
Subject = "Netcool/Impact Notification";
Message = "Some problem was encountered";
Sender = "impact";
ExecuteOnQueue = false;
SendEmail(null, Addresses, Subject, Message, Sender, ExecuteOnQueue);

You can override the SMTP host and SMTP port values that are defined in the EmailSender service, from inside the SendEmail function.

If you do not specify the SMTP host and SMTP port before you use the SendEmail function call, the system uses the SMTP host and SMTP port values that are defined in the EmailSender service. If you want to override the SMTP host and the SMTP port in the service, add the following information to the SendEmail function:

SmtpHost = "hostname.example.com";
SmtpPort = <port number example>;
SendEmail(...);

In this example, the SMTP host is provided by the EmailSender service.

SmtpPort = 587;
SendEmail(...);

In this example, the SMTP port is provided by the EmailSender service.

SmtpHost = "hostname.example.com";
SendEmail(...);

Enabling HTML format and authentication

You can also set some optional properties to enable HTML formatting or to pass authentication credentials to the email server.

If you enable HTML formatting, the body text of the email can be formatted with bold and other fonts, tables, and, lists and other formats. HTML formatting does not apply to the subject of the email. Firstly, create a new object to hold the properties.

CallProps = NewObject();

To enable HTML formatting, set the content type to text/html. For example:

CallProps.EmailContentType="text/html";

Pass the CallProps object to the SendEmail function as a parameter:

SendEmail(null, Address, Subject, Message, Sender, ExecuteOnQueue, Attachment, CallProps);

For example:

Addresses = NewObject();
Addresses.To = 'user@example.com';
Subject = "Testing the HTML mail ";
Message = "<html>This is a <b>HTML</b> <i>email</i>.<br>End of message</html>";
Sender = "impact";
ExecuteOnQueue = false;
Attachment = null;

CallProps = NewObject();
CallProps.EmailContentType="text/html";

SendEmail(null, Address, Subject, Message, Sender, ExecuteOnQueue, Attachment, CallProps);

You can enable authentication so that a user must use a user name and password to connect to the email server. For example:

CallProps.UseAuth=true;
CallProps.AuthUser="some email";
CallProps.AuthPassword="plaintext or encrypted password using Encrypt or nci_crypt";

If an encrypted password is used the following syntax must be used:

CallProps.DecryptPassword=true;

To pass the CallProps to the SendEmail function use the following example:

SendEmail(null, Address, Subject, Message, Sender, ExecuteOnQueue, Attachment, CallProps);

Inserting images

Images can be inserted into HTML emails by either linking to an externally hosted image, encoding the image as a base64 string or attaching it inline with the EmailImages attribute.

Linking to an external image

In the message body, link to the URL where the image is hosted. For example:

Message = '<html><body>This is an HTML message <img src="http://example/test.jpg"/>.<br></body></html>';

Note: Some email clients may block the image unless the image host is from a trusted sender or domain.

Embedding a base64 encoded image

Create a base64 encoded image and add it to the message body. For example:

Message = '<html><body>This is an HTML message <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAYAAACp8Z5+AAAAE0lEQVR42mP0yL31nwEJMJIuAACUmQo96mdYQgAAAABJRU5ErkJggg=="> </body></html>';

Note: Some email clients may block base64 encoded images. Encoding images as a base64 string is not recommended for large images.

Using the EmailImages attribute

version 7.1.0.28+ You can use the EmailImages attribute to insert inline images into an HTML formatted email.

Create a new object and declare each image with its name and file path.

// Create a new object
ImagesObj = NewObject();

// Declare each image as a key value pair attribute
ImagesObj.image1 = "/opt/IBM/tivoli/impact/user.png";
ImagesObj.image2 = "/opt/IBM/tivoli/impact/group.png";

In the CallProps parameter, set EmailImages to use the image object. The email content type must be set to text/html.

CallProps.EmailImages = ImagesObj;
CallProps.EmailContentType="text/html";

In the message body, add the image to the HTML code the cid: prefix. For example:

Message = '<html><body>This is an HTML message <img src="cid:image1"/>.<br><img src="cid:image2"/></body></html>';

Addresses = NewObject();
Addresses.To = "to@example.com";
Subject = "Netcool/Impact Notification";
Sender = "impact";
ExecuteOnQueue = false;
Attachment = null;

CallProps = NewObject();
CallProps.EmailContentType="text/html";

ImagesObj = NewObject();
ImagesObj.image1 = "/opt/IBM/tivoli/impact/error.png";
ImagesObj.image2 = "/opt/IBM/tivoli/impact/companylogo.png";

Message = '<html><body>Some problem was encountered <img src="cid:image1"/>.<br><img src="cid:image2"/></body></html>';

SendEmail(null, Addresses, Subject, Message, Sender, ExecuteOnQueue, Attachment, CallProps);

Sending attachments

You can attach a file to the email using the Attachment parameter:

Attachment = "/opt/IBM/tivoli/impact/example.pdf";

The following example will send an email with a single file attachment:

Addresses = NewObject();
Addresses.To = "to@example.com";
Subject = "Netcool/Impact Notification";
Message = "Some problem was encountered";
Sender = "impact";
ExecuteOnQueue = false;

CallProps = NewObject();
CallProps.EmailContentType="text/html";

CallProps.UseAuth=true;
CallProps.AuthUser="some email";
CallProps.AuthPassword="plaintext or encrypted password using Encrypt or nci_crypt";

// The file location must be on the local filesystem and accessible by the Impact server
Attachment = "/opt/IBM/tivoli/impact/example.pdf";

SendEmail(null, Addresses, Subject, Message, Sender, ExecuteOnQueue, Attachment, CallProps);

To attach multiple files, use a semi-colon between file names:

Attachment = "/opt/IBM/tivoli/impact/example.pdf;/opt/IBM/tivoli/impact/test.zip";

Multipart messages

By default, the SendEmail function will send emails as multipart messages with the multipart/mixed content type. The content type and encoding for each part is automatically set to appropriate values.

You can disable the use of multipart messages and force all outgoing emails to use a single text/plain content type by re-configuring the EmailSender service. See Configuring the Email sender service for more information.

version 7.1.0.31+ You can also disable the multipart container for individual emails by setting the following property in the SendEmail parameters:

CallProps.ContentTypePlainText=true;

version 7.1.0.31+ The Content-Transfer-Encoding header for text parts is automatically determined based on the content. You can set an explicit encoding for the text parts of an email with the following property:

// Allowed values include "base64", "quoted-printable", "7bit", "8bit" or "uuencode".
CallProps.ContentTransferEncoding="base64";