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.
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.
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.
Parameter |
Format |
Description |
---|---|---|
|
Data item |
Data item of any data type whose |
|
String or a context object |
Email address for the recipient of the email. If this parameter is specified, the
|
|
String |
Subject for the message. |
|
String |
Message body for the email. |
|
String |
Email address for the sender for the email. |
|
Boolean |
Specifies whether
to place the outgoing message in the queue that is governed by the
command execution manager service. If you specify |
|
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.
Parameter |
Format |
Description |
---|---|---|
|
String |
Set the value of the |
|
Boolean |
Enable authentication if the email server requires it for access. |
|
String |
The user name used for authentication. |
|
String |
The password used for authentication. The password can be in plaintext or encrypted with
|
|
Boolean |
If set to |
|
Object |
|
|
Boolean |
If set to |
|
Boolean |
|
|
String |
|
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.
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 theSendEmail
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:
If an encrypted password is used the following syntax must be used:CallProps.UseAuth=true; CallProps.AuthUser="some email"; CallProps.AuthPassword="plaintext or encrypted password using Encrypt or nci_crypt";
To pass the CallProps to the SendEmail function use the following example:CallProps.DecryptPassword=true;
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>';
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>';
base64
encoded images. Encoding images as a
base64
string is not recommended for large images.Using the EmailImages
attribute
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.
You can also disable the multipart container for individual
emails by setting the following property in the SendEmail parameters:
CallProps.ContentTypePlainText=true;
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";