Class Mail

TopLevel.Object
- dw.net.Mail

This class is used to send an email with either plain text or MimeEncodedText content. Recipient data (from, to, cc, bcc) and subject are specified using setter methods. When the send() method is invoked, the email is put into an internal queue and sent asynchronously.

Note: when this class is used with sensitive data, be careful in persisting sensitive information to disk.

The following example script sends an email with MimeEncodedText content:

See Sending email via scripts or hooks in the documentation for additional examples.

Property	Description
bcc: List	Gets the `bcc` address List.
cc: List	Gets the `cc` address List.
from: String	Gets the email address to use as the `from` address for the email.
replyTo: List `(read-only)`	Gets the `replyTo` address List.
subject: String	Gets the `subject` of the email.
to: List	Gets the `to` address List where the email is sent.

Constructor	Description
Mail()

Method	Description
addAttachment(File)	Adds a file attachment to the email.
addBcc(String)	Adds an address to the `bcc` List.
addCc(String)	Adds an address to the `cc` List.
addReplyTo(String)	Adds an address to the `replyTo` List.
addTo(String)	Adds an address to the `to` address List.
getBcc()	Gets the `bcc` address List.
getCc()	Gets the `cc` address List.
getFrom()	Gets the email address to use as the `from` address for the email.
getReplyTo()	Gets the `replyTo` address List.
getSubject()	Gets the `subject` of the email.
getTo()	Gets the `to` address List where the email is sent.
send()	prepares an email that is queued to the internal mail system for delivery.
setBcc(List)	Sets the `bcc` address List.
setCc(List)	Sets the `cc` address List where the email is sent.
setContent(MimeEncodedText)	Mandatory Uses MimeEncodedText to set the content, MIME type and encoding.
setContent(String)	Mandatory Sets the email content.
setContent(String, String, String)	Mandatory Sets the email content, MIME type, and encoding.
setFrom(String)	Mandatory Sets the sender address for this email.
setListUnsubscribe(String)	Sets the List-Unsubscribe header value to work with List-Unsubscribe-Post to allow integration with an externally-managed mailing list.
setListUnsubscribePost(String)	Sets the List-Unsubscribe-Post header value.
setSubject(String)	Mandatory sets the `subject` for the email.
setTo(List)	Sets the `to` address List where the email is sent.
static validateAddress(String)	Validates the address that is sent as parameter.

assign, create, create, defineProperties, defineProperty, entries, freeze, fromEntries, getOwnPropertyDescriptor, getOwnPropertyNames, getOwnPropertySymbols, getPrototypeOf, hasOwnProperty, is, isExtensible, isFrozen, isPrototypeOf, isSealed, keys, preventExtensions, propertyIsEnumerable, seal, setPrototypeOf, toLocaleString, toString, valueOf, values

bcc: List: Gets the bcc address List.

cc: List: Gets the cc address List.

from: String: Gets the email address to use as the from address for the email.

replyTo: List (read-only): Gets the replyTo address List.

subject: String: Gets the subject of the email.

to: List: Gets the to address List where the email is sent.

Mail()

addAttachment(file: File): Mail

Adds a file attachment to the email. This method is restricted to Job context only.

Parameters:

file - The file to be attached to the email. Must not be null and must exist.

Returns:

this Mail object

Throws:

IllegalArgumentException - if the file is null, doesn't exist, or is not a file

addBcc(bcc: String): Mail

Adds an address to the bcc List. Address must conform to the RFC822 standard.

Parameters:

bcc - new bcc address to add to bcc address List.

Returns:

this Mail object.

addCc(cc: String): Mail

Adds an address to the cc List. The address must conform to RFC822 standard.

Parameters:

cc - new cc address to be added to cc address List.

Returns:

this Mail object.

addReplyTo(replyTo: String): Mail

Adds an address to the replyTo List. Address must conform to the RFC822 standard.

Parameters:

replyTo - new replyTo address to add to replyTo address List.

Returns:

this Mail object.

Throws:

IllegalArgumentException - if the email address is invalid

addTo(to: String): Mail

Adds an address to the to address List. The address must conform to the RFC822 standard.

Parameters:

to - email address to add to the to address List.

Returns:

this Mail object.

getBcc(): List

Gets the bcc address List.

Returns:

bcc address List or empty List if no bcc addresses are set.

getCc(): List

Gets the cc address List.

Returns:

cc address List or empty List if no cc addresses are set.

getFrom(): String

Gets the email address to use as the from address for the email.

Returns:

the from address for this mail or null if no from address is set yet.

getReplyTo(): List

Gets the replyTo address List.

Returns:

replyTo address List or empty List if no replyTo addresses are set.

getSubject(): String

Gets the subject of the email.

Returns:

subject or null if no subject is set yet.

getTo(): List

Gets the to address List where the email is sent.

Returns:

to address List or empty List if no to addresses are set.

send(): Status

prepares an email that is queued to the internal mail system for delivery.

Returns:

Status which tells if the mail could be successfully queued ( Status.OK) or not ( Status.ERROR). If an error is raised, more information about the reason for the failure can be found within the log files. If the mandatory fields from, content, and subject are empty an IllegalArgumentException is raised. An IllegalArgumentException is raised if neither to, cc nor bcc are set.

setBcc(bcc: List): Mail

Sets the bcc address List. If there are already bcc addresses they are overwritten.

Parameters:

bcc - list of Strings representing RFC822 compliant email addresses. List replaces any previously set list of addresses. Throws an exception if the given list is null.

Returns:

this Mail object.

setCc(cc: List): Mail

Sets the cc address List where the email is sent. If there are already cc addresses set, they are overwritten. The address(es) must conform to the RFC822 standard.

Parameters:

cc - List of Strings representing RFC822 compliant email addresses. This List replaces any previously set List of addresses. Throws an exception if the given List is null.

Returns:

this Mail object

setContent(mimeEncodedText: MimeEncodedText): Mail

Mandatory Uses MimeEncodedText to set the content, MIME type and encoding.

Parameters:

mimeEncodedText - MimeEncodedText from which the content, MIME type, and encoding information is extracted.

Returns:

this Mail object.

setContent(content: String): Mail

Mandatory Sets the email content. The MIME type is set to "text/plain;charset=UTF-8" and encoding set to "UTF-8".

Parameters:

content - String containing the content of the email.

Returns:

this Mail object.

setContent(content: String, mimeType: String, encoding: String): Mail

Mandatory Sets the email content, MIME type, and encoding. No validation of MIME type and encoding is done. It is the responsibility of the caller to specify a valid MIME type and encoding.

Parameters:

content - String containing the content of the mail
mimeType - mime type of the content. For example "text/plain;charset=UTF-8" or "text/html"
encoding - character encoding of the email content. For example UTF-8-8

Returns:

this Mail object.

setFrom(from: String): Mail

Mandatory Sets the sender address for this email. The address must conform to the RFC822 standard.

Parameters:

from - String containing a RFC822 compliant email address

Returns:

this Mail object.

setListUnsubscribe(listUnsubscribe: String): Mail

Sets the List-Unsubscribe header value to work with List-Unsubscribe-Post to allow integration with an externally-managed mailing list.

Parameters:

listUnsubscribe - The List-Unsubscribe header value, e.g., "https://example.com/unsubscribe"

Returns:

this Mail object

setListUnsubscribePost(listUnsubscribePost: String): Mail

Sets the List-Unsubscribe-Post header value. This header supports one-click unsubscribe functionality.

Parameters:

listUnsubscribePost - The List-Unsubscribe-Post header value, typically "List-Unsubscribe=One-Click"

Returns:

this Mail object

setSubject(subject: String): Mail

Mandatory sets the subject for the email. If the subject is not set or set to null at the time send() is invoked and IllegalArgumentException is thrown.

Parameters:

subject - subject of the mail to send.

Returns:

this Mail object.

setTo(to: List): Mail

Sets the to address List where the email is sent. If there are already to addresses, they are overwritten.

Parameters:

to - list of Strings representing RFC822 compliant email addresses. List replaces any previously set List of addresses. Throws an exception if the given List is null.

Returns:

this Mail object

static validateAddress(address: String): Boolean

Validates the address that is sent as parameter. This validation includes:

The format must match RFC822
The address must be 7-bit ASCII
The top-level domain must be IANA-registered
Sample domains such as example.com are not allowed

Parameters:

address - Email address to be validated

Returns:

true if valid, false otherwise