MAIL

The MAIL action provides the capability to email one or more users.  The body of the email is defined within an email template designed by the administrator.  The syntax is:

{MAIL: 'template_name’ [user_list | [FROM:user_list] [REPLY_TO:user_list] | [CC:user_list] | [BCC:user_list] | [SEND_ONE_EMAIL] | [INCLUDE:ATTACHMENTS]] }

  • You may use a space character or a comma as the delimiter between parameters
  • user_list is a structure that defines a combination of USER ID's, Roles and email addresses.  The syntax for a user_list is:

        [field_name | [ROLE:]role | USER:user_id | email_address ]*

    • The * indicates that you may repeat these parameters
    • The field_name is either a text field containing a user ID or email address or is a user field
    • The field_name contains one or more values which are USER ID's to be processed within the action.  Only valid USER ID's stored within ExtraView are processed and if the installation uses an external directory such as LDAP, no check on the validity of the USER ID's are made
    • The field_name may alternatively or additionally contain one or email addresses to which the notification is sent
    • The optional ROLE:role parameter generates the notification to all active users who may assume the role
    • The optional USER:user_id parameter generates the email notification to a valid USER ID
    • The optional email_address parameter generates the email notification to the email address
  • template_name is the name of a predefined email template to be used as the body of the email
  • The optional FROM:user_list parameter is used to provide an alternative user's primary email address as the sender of the mail.  The default email address that is used as the sender is the value within the behavior setting named EMAIL_FROM_USER_ID.  The user may be either the name of a user, or their user ID
  • The optional REPLY_TO:user_list parameter is used to provide an alternative email address as the Reply To address of the mail.  The default REPLY TO email address that is used as the sender is the value within the behavior setting named EMAIL_FROM_USER_ID
  • The optional CC: parameter and associated list of users or email addresses are sent via the email CC line
  • The optional BCC: parameter and associated list of users or email addresses are sent via the email BCC line
  • The optional SEND_ONE_EMAIL parameter is used, a single email is generated and sent to all recipients, irrespective of their role and permissions.  If this is not entered then a single email is generated and sent to each recipient, and that user's role and permissions are used for each email
  • The optional  INCLUDE:ATTACHMENTS parameter is used to add any selected attachments (via the Select?​ check boxes displayed by each attachment) into the outgoing email so that they will be delivered along with the email.

It is not valid to use this action within the mail directive. It is most typically used within the preupdate or postupdate directives.

Both HTML and text-based email templates may be sent with this action. This is controlled by the format of the template itself, and a simple naming convention for the template. The processing for this action requires either the template_name or the template_title to follow the MAIL: action. If this name or title has a suffix of .txt, then any email generated to a user whose personal email format is full, brief or very brief text will be generated in text. All other mails will be generated as HTML. This implies that if you want email templates where some users will receive HTML mail and others will receive text, you should create two templates. For example, you might have one template named Customer_Response_Template with the HTML and another named Customer_Response_Template.txt with the text.

When creating text-based email templates, make sure that you use the WYSIWYG (what-you-see-is-what-you-get) mode of the email template utility and be sure that the template does not contain any HTML tags.

In the email rule action, use the HTML template name or title, but without the .txt suffix.

If a text template does not exist, all users will receive the HTML template as a result of the action. If a text template exists, users with text email format preferences will receive the text email template. If an HTML template does not exist and a text template does exist, then all users will receive the text template.

Examples

  1. { MAIL: 'Sales Response Template', BSMITH, GLONG }

    This emails the Sales Response Template to the users BSMITH and GLONG
     

  2. { MAIL: 'Contact Form', CONTACT_FIELD }

    This example sends the template named Contact Form to the user whose email address appears within the CONTACT_FIELD on the form
     

  3. { MAIL: 'Claim Form', USER_FIELD, FROM:ASSIGNED_TO, REPLY_TO:ASSIGNED_TO, INCLUDE:ATTACHMENTS }

    This emails the Claim Form template to the user who is selected in USER_FIELD, with the mail from address being set as the value of the ASSIGNED_TO field, the reply to address being set as the value of the ASSIGNED_TO field and including the attachments to the issue