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.

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, ....)

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();