Service call type: AQ_MailService [editor]

What is it for?

AQ_MailService is used to send e-mails using Assets. This Asset is used as body text that can in turn (optionally) contain HTML tags.

Parameters

Name	Description	Type	Required
addresses-to-expr	An expression which results in an email address or list of addresses. The text format must adhere to the RFC822 standard. See also the Tips section below.	String	Yes
addresses-cc-expr	An expression which results in an email address or list of addresses. The text format must adhere to the RFC822 standard.	String	No
addresses-bcc-expr	An expression which results in an email address or list of addresses. The text format must adhere to the RFC822 standard	String	No
address-from	An expression which results in an email address. The text format must adhere to the RFC822 standard	String	Yes
addresses-reply-to-expr	An expression which results in an email address or list of addresses. The text format must adhere to the RFC822 standard. Since Blueriq 17.7	String	No
mail-asset	The name of the asset that contains the subject and the body of the email. Note: The type of the asset must be “Email” and should contain only one line of text.	String	Yes
smtp-host	The hostname of the SMTP server.	String	No
smtp-port	The port of the SMTP server.	Integer	No (defaults to 25)
smtp-user	The username to use when connecting to the SMTP server.	String	No
smtp-password	The password to use when connecting to the SMTP server.	String	No
smtp-usetls	Indicates if the SMTP server should be contacted using TLS (Transport Layer Security).	Boolean	No (defaults to false)
Documents	Specify all documents to be generated and attached. (deprecated, use connection instead)	Document	No
Connection	Specify the connection. It is used for document attachments	String	No
FileIds	Specify one or more file ids. When using this parameter, you also need to use the Connection parameter.	Expression	No

Events

MailSizeExceeded: When the mail server indicates the combined size of all attachments is too large to be send, this exit is taken so that you can give a clear indication to the end user. If the max size is exceeded and this exit event is not mapped, an error is thrown.

When specifying email address values in the parameters above, expression statements are to be used.

For a simple hard coded email address, an expression containing a constant value suffices:

"romeo@example.org"

The parameters addresses-to-expr, addresses-cc-expr or addresses-bcc-expr can deal with a list of values. In that case, the expression should reflect this:

["romeo@example.org", "juliet@example.com"]

Using the expression, addresses can be retrieved:

COLLECT person.mailaddress FROM ALL person WHERE (person.mailaddress != ?)

The AQ_MailService supports adding phrases to mail addresses (where the 'phrase' typically is a for humans readable identifier of the mail address. The format for an email address using a phrase is: Romeo <romeo@example.org>

Typically, phrases can be surrounded by the double-quote character ("). Within Blueriq, this character signifies the beginning or end of an expression. To prevent problems, the AQ_MailService accepts unquoted phrases (before submitting a message to an email server, the AQ_MailService makes sure that all phrases are properly formatted). As a result, each of these examples are valid mail address definitions within the AQ_MailService:

"Romeo <romeo@example.org>"
"Romeo Capulet <romeo@example.org>"
"Capulet, R. <romeo@example.org>"
["Romeo <romeo@example.org>", "Juliet <juliet@example.com>"]
["Romeo Capulet <romeo@example.org>", "Juliet Montague <juliet@example.com>"]
["Capulet, R. <romeo@example.org>", "Montague, J. <juliet@example.com>"]

Properties

Some AQ_MailService parameters can be set in the application.properties file , such as in the following example.

application.properties

blueriq.connection.[AQ_MailService name from Encore].email.smtp=exampleDomain.com (for the smtp-host parameter)
blueriq.connection.[AQ_MailService name from Encore].email.smtpport=25 (for the smtp-port parameter)
blueriq.connection.[AQ_MailService name from Encore].email.username=userName (for the smtp-user parameter)
blueriq.connection.[AQ_MailService name from Encore].email.password=password (for the smtp-password parameter)
blueriq.connection.[AQ_MailService name from Encore].email.usetls=true (for the use-tls parameter)
blueriq.connection.[AQ_MailService name from Encore].email.fromaddress=test@yourDomain.com (for the address-from parameter)
# repytoaddresses is available since Blueriq 17.7
blueriq.connection.[AQ_MailService name from Encore].email.replytoaddresses=reply-to@example.com (for the addresses-reply-to-expr parameter)
blueriq.connection.[AQ_MailService name from Encore].email.toaddresses=test1@example.com (for the addresses-to-expr parameter)
blueriq.connection.[AQ_MailService name from Encore].email.ccaddresses=test2@example.com (for the addresses-cc-expr parameter)
blueriq.connection.[AQ_MailService name from Encore].email.bccaddresses=test3@example.com (for the addresses-bcc-expr parameter)

Default mail connection properties

When a AQ_MailService connection name is not defined in the properties, the runtime will fall back on the defined default property. The default properties can be defined as shown in the following example. When a specific property for an AQ_MailService is not defined, it will fall back on the default properties. If no default properties are set, it will fall back on the Encore parameters.

application.properties

blueriq.connection.email.smtp=exampleDefaultDomain.com (for the smtp-host parameter)
blueriq.connection.email.smtpport=25 (for the smtp-port parameter)
blueriq.connection.email.username=defaultUserName (for the smtp-user parameter)
blueriq.connection.email.password=defaultPassword (for the smtp-password parameter)
blueriq.connection.email.usetls=true (for the use-tls parameter)
blueriq.connection.email.fromaddress=default@yourDomain.com (for the address-from parameter)
# repytoaddresses is available since Blueriq 17.7
blueriq.connection.email.replytoaddresses=reply-to@example.com (for the addresses-reply-to-expr parameter)
blueriq.connection.email.toaddresses=default1@example.com (for the addresses-to-expr parameter)
blueriq.connection.email.ccaddresses=default2@example.com (for the addresses-cc-expr parameter)
blueriq.connection.email.bccaddresses=default3@example.com (for the addresses-bcc-expr parameter)

When the e-mail addresses are configured through the property files, it's not possible to use expressions or any Blueriq logic to derive them from attributes (use Encore configuration instead).

Also note the following points:

The fromaddress property can be only 1 e-mail address.
The replytoaddresses, toaddresses, ccaddresses and bccaddresses may contain more than one address. Multiple addresses may either be separated by a comma ',' or by a semicolon ';'.
If one of the address properties is not filled, it will fallback to the default property. If the default property is not filled, it will fall back on the Encore parameters for that one property (it's possible to only configure the fromaddress as property and the other addresses in Encore).

E-mail addresses configured in properties may contain the following formats:

romeo@example.org
romeo@example.org, juliet@example.com
romeo@example.org; juliet@example.com
"romeo@example.org"; "juliet@example.com"
Romeo Capulet <romeo@example.org>
Romeo Capulet <romeo@example.org>, Juliet Montague <juliet@example.com>
Romeo Capulet <romeo@example.org>; Juliet Montague <juliet@example.com>
romeo@example.org, Juliet Montague <juliet@example.com>
"romeo@example.org"; "Juliet Montague <juliet@example.com>"

Note: some of the above properties are mandatory in Encore, those can be filled in Encore with a dummy value if you always want to overwrite them with a property.

It is not recommended to specify the password in Encore because the value of the smtp-password parameter is saved in plain text in the project xml which can lead to security issues. We recommend saving the password in the application.properties file where it can be encrypted.

When you want to send an email from a different address or alias, then you need to configure that on the mail service.

Here is the documentation on how to do that for Gmail: https://support.google.com/a/answer/22370?hl=en

When this is not set correctly, you will experience that the mail send from the mail address that is configured for authentication with TLS.

Enabling DomainKeys Identified Mail

AQ_MailService supports protecting against email spoofing using DKIM. It can be enabled or disabled per sender domain, but not per email address individually.

For enabling this feature, a set of keys has to be present:

A private key placed on the server running the Runtime in order to sign the email message;
A public key available in the DNS of the recipient (so either at ISP level, a sender public facing DNS server or a recipient private DNS server).

Runtime Configuration

In application.properties, add the following settings for each domain where DKIM should be activated:

blueriq.mail.domain_alias=something.com
blueriq.mail.domain_alias.dkim.enabled=true # default false
blueriq.mail.domain_alias.dkim.selector=dkim # default empty
blueriq.mail.domain_alias.dkim.privateKeyFile=<path to pem file> # error if not set and dkim enabled, error if not readable pem file

Details:

The first setting allows aliasing of domain names to a short name. In the example, the something.com domain will be referred subsequently as domain_alias.
DKIM can be enabled and disabled per domain by setting mail.<domain alias>.enabled = [true|false].
The selector option specifies the DNS selector. The queried TXT record should be in the form <selector>.domainkey.<domain> (see Wikipedia for details).
The private key file is used to sign the email message. It should be a readable pem file. It is highly recommended to properly secure this file.

No special configuration at the service definition level is required.

Testing DKIM

Assuming the email messages are sent correctly, there are two ways of checking that DKIM actually works. Both these methods assume the DNS TXT record is published by the sender domain (public corporate DNS server or ISP DNS server) properly:

Send an email to a Gmail or Yahoo Mail account. The email should appear as secured when using the procedure described at http://www.appmaildev.com/en/dkim/.
Use an online DKIM validator (just google "test dkim").

If the public key is not available publicly (so in the recipient private DNS only), you should first check if the public key is available on the receiving server. Something like "dig TXT <selector>.domainkey.<domain>" should return the public key if the DNS is correctly configured.

For local testing, Blueriq uses a BIND + postfix + opendkim linux setup.

Space shortcuts

Page tree