Mail Functions in DIAL

Sends an email message with the contents of the local file identified by filename. To use bcc without using cc, use an empty string ("") as a placeholder for cc.

NOTE: Starting with DIAL 7.1(15), when in server mode, mail.file() only uses files from the project.

Loads attributes for sending mail from the given file. The file contains a sequence of attribute name value pairs, and the settings override any current settings for these mail attributes that have been previously set in dial. This function allows all mail settings to be set in an external file, so that multiple DIAL scripts can share these settings, as well as handle a large number of settings needed for complex authentication schemes such as Open ID Connect.

The file is a series of lines of the form:

<attribute name> <whitespace> <attribute value>

The following attributes can be set:

Here are some examples of attribute files:

Setting various mail settings, in a situation where no authentication is required:

server mail.example.com

from "Daily Diver Data" <[email protected]>

Settings for basic authentication:

server mail.example.com

user nobody

password secret

Settings for xoauth authentication with Outlook:

client_id 12345678-90ab-cdef-1234-567890abcdef

scope https://outlook.office365.com/.default

client_secret_file /keys/client.secret

token_url https://login.microsoftonline.com/fedcba09-8765-4321-fedc-ba0987654321/oauth2/v2.0/token

tls required

Sends an email message with the contents of multiple local files as different parts of a multipart mail message. Each file is identified by a separate filename. There are two argument formats for mail.multipart():

mail.multipart(to, subject, filename1, options1, filename2, options2, ....)

or

mail.multipart_cc(to, cc, bcc, subject, filename1, options1, filename2, options2, ....)

NOTE: Starting with DIAL 7.1(15), when in server mode, mail.multipart() only uses files from the project.

Sets the return_address for email messages. The address appears in the From: header of the message. If this function is not called, the local user is used as the return address.

TIP: If a Mail server does not recognize the "From" address as yours, it may ignore it. You may need to research your mail service to determine how to add additional addresses that you can send mail from.

Requests a read receipt for an email message by using the Disposition-Notification-To attribute and provides privacy information by using the Sensitivity attribute. The addressee value in the Disposition-Notification-To format is the email address of the user from whom the receipt is requested. The value for Sensitivity can be set to Company-Confidential, Personal, or Private, and is displayed in the header of the email. There are two argument formats for mail.set_header():

mail.set_header("Disposition-Notification-To", addressee)

or

mail.set_header("Sensitivity", value)

Instructs DIAL to use the specified hostname instead of the machine's canonical host name when sending mail. This change is only visible in the headers of the email, which many mail clients do not reveal to the user. This is intended for use on multi-homed machines, which have multiple IP addresses and host names, when the user wants the headers to use one of the machine's alternate (non-canonical) host names. Normally, this function is not needed.

Sets the return_address for email messages, where the return_address is not the same as the address in the From: header. The return address appears in the Reply To: header of the message. If this function is not called, the Reply To: header is blank and the local user is used as the return address.

Sets the Internet Mail Server that is used to send email messages over the SMTP protocol. If this function is not called, the local machine is used as the mail server. The port number is not required, but it can be specified in the string as server_name:port.

Sets the SMTP port to a number besides the default port 25.

Enables or requires encryption via Start-TLS when sending email. Status is either disabled, enabled, or required. The default status is disabled. The set_tls function tests whether the SMTP server from which mail is sent is employing transport layer security (TLS) encryption. Start-TLS is assumed to run on port 587. If not using Start-TLS, the port defaults to 465.

If the feature is enabled, and Start-TLS is not enabled or the server certificate is not trusted, then the mail is still sent, assuming the server accepts the unencrypted message. If the feature is required, the mail is not sent unless Start-TLS is enabled and the server certificate is trusted. In the event of a certificate error, a warning is printed.

NOTE: The Java Runtime Environment (JRE) has its own list of trusted Certificate Authorities, which might differ from those available to, for example, web browsers on the system. There is a Java Keystore file at lib/security/cacerts in the JRE's folder. To add a certificate, such as my-cert.crt to this store, run the following command:

cd <JRE LOCATION>/lib/security keytool -importcert -file my-cert.crt -alias "short description" -keystore cacerts

The default keystore password for cacerts is "changeit".

Sets the username and password for use with authenticated SMTP. This function is needed for Mail Servers that require users to be authenticated to send mail. DIAL supports the LOGIN mechanism for SMTP authentication, as defined by RFC2554. If this function is not called, authenticated SMTP is not used.

TIP: You cannot SMTP AUTH (use a username and password to send mail) with an account that requires multi-factor authentication (MFA) in a batch environment. You may need to setup a special account to handle the mail. Check the email vendor's documentation.

Switches mail sending to a test mode so that email messages are not delivered to the intended recipient(s). This function is useful for testing new DIAL scripts without accidentally sending incorrect information to users. Without any arguments, mail.test() disables all mail sending, so that a call to mail.text(), mail.file(), or mail.multipart() simply results in a log message. With a single argument, the mail messages are sent to the specified test_address instead of to the recipient listed in the call.

Sends an Internet email message with the specified string text as the text of the message.

This example connects to the DiveLine server, opens the test_marker.mrk Marker, saves the report as a pdf file, and emails the file to [email protected] with a subject of Revenue Report.

mail.set_server("mail.company.com");

mail.set_from("[email protected]");

 

diveline.connect("localhost", "dial_user");

diveline.set_project("myProject");

 

marker.open(mymodel,"/models/test_marker.mrk");

marker.save_window(mymodel,"../temp/test_marker.pdf", "pdf");

mail.file("[email protected]", "Revenue Report", "../temp/test_marker.pdf", "pdf,attach,filename=test_marker.pdf");

 

diveline.disconnect();

This example connects to the DiveLine server and opens a marker showing revenue by Sales Manager. It then saves the report as an html file and as a pdf file, and emails both files to [email protected] with a subject of Report. The script sends a carbon copy of the message to [email protected] and a blind carbon copy to [email protected].

mail.set_server("mail.company.com");

mail.set_from("[email protected]");

 

diveline.connect("localhost", "dial_user");

diveline.set_project("myProject");

 

marker.open(mymodel,"/models/test_marker.mrk");

marker.save_window(mymodel,"../temp/test_marker.pdf", "pdf");

marker.save_window(mymodel,"../temp/test_marker.html", "html");

 

mail.multipart_cc("[email protected]", "[email protected]", "lord @company.com", "Report",

"/temp/test_marker.pdf" , "pdf, attach",

"/temp/test_marker.html", "html, attach" );

 

diveline.disconnect();