Customizing Mail Express Pages and Notifications

Customization is available for the Mail Express web pages and for the various email notifications that Mail Express sends. You can modify all interfaces that have Globalscape or Mail Express branding, including Web portal headers, footers, and logos, and Mail Express-added email content. (The Globalscape Professional Services team provides custom branding services.) All customizations are file-based; that is, you can create customized text and image files and place them in a specified location. If any customization contains invalid variables or formatting, the default notifications are used and an error is displayed in the Audit Event History report to inform you of the issue. (The Audit Event History report will display a Template Customization error.)

Mail Express uses the Freemarker Template Engine to handle processing the template files (.FTL). Refer to the Freemarker website for more information about editing Freemarker templates.

Customizations are performed by editing the templates located in <Installation Directory>\webapps\ROOT\WEB-INF\template. The Mail Express Server service does not require a restart for changes to the templates to take effect.

Each template includes minimal Globalscape branding as a footer on each web page and email.
Attachment email headers read, "The following attachments have been securely sent to you and can be downloaded until <expiration_date>."
The time and date format for all notifications is Month Day, Year HH:MM:SS AM/PM. For example: June 20, 2013 3:11:44 PM CDT. The time is the local server time.
The default welcome text on any portal page is "Welcome to the Mail Express <name> Portal" where <name> is File Dropoff, Internal, or Pickup.
The default welcome text on any login page is "Welcome to the Mail Express <name> Login Page" where <name> is Administration, File Dropoff, or Internal.
Customized files in the \template\ directory are automatically backed up during reinstall or upgrade. You must migrate your customizations to the new templates rather than simply copying your old templates into the directory, because the new templates may have functionality changes.

For example, if you wanted to include a custom URL that recipients could click in the email that Mail Express sends to them so that they can access your custom Drop-Off portal to return files, you would edit the addinsendtemplate.html.ftl template to include the custom link:

<#if packageLinkOnly>

<a href="${packageLink}">Download <#if attachments?size == 1>attachment<#else>attachments</#if></a> Please use this customized Mail Express <a href="https://mesrv/dropoff/to/${sender.utfText}">Drop-Off</a> link to return any files to me.

<#else>

Additional download options are available at the <a href="${packageLink}">Pick-Up Portal</a>. Please use this customized Mail Express <a href="https://mesrv/dropoff/to/${sender.utfText}">Drop-Off</a> link to return any files to me.

</#if>

The text in red was added to the existing text in the template.

Email Templates

Mail Express uses a variety of templates to build the various emails that it sends. You can customize the text and some text attributes in the template.

The templates are purposefully very simple. The text of the email is editable. The email address and link are added with variables. (Be careful to not change any of the variables in angle brackets, <variable>, as that will prevent the email from functioning properly.)

Each of the emails is composed of the following template types:

<ID>.html.ftl is the template for the HTML-formatted version of the email that will be seen by recipients using HTML mode to view emails in their email client software.
<ID>.subject.ftl is the template for the subject line of the email
<ID>.text.ftl is the template for the text-formatted version of the email that will be seen by recipients using plain text to view emails in their email client software.

If you want HTML email recipients and plain-text email recipients to view the same message, you will have to edit both versions of the template. The subject template applies to both HTML and plain text.

Common Template Data Structures

Many templates use data in a common format. The properties of these structures are detailed in the table.

Structure	Description	Properties
Actor	Represents a user account	emailAddress: String; account email address; e.g. "joe.bloggs@example.com" username: String; account user name; e.g. "joe.bloggs" displayName: String; account display name; may be null; e.g. "Joe Bloggs" personalizedAddress: String; combines display-name and email-address; e.g. [Joe Bloggs <joe.bloggs@example.com>] kind: String; type of account: Administrator – administrators InternalAutomatic – internal users from LDAP InternalManaged – internal users manually added External – drop-off users
Attachment	Represents a file attachment to an email	title: String; the document title length: Double; the document size unit: String; the document unit: Kb, MB, etc link: String; document access URL
Problem	Represents a system error	title: String; a brief name of the issue description: String; more detailed description of the issue level: Integer; nesting level for the issue; used when they are chained together based on root cause; the initial level is 0
AccountSummary	Represents a user account from an invitation	actor: Actor; the account holder portal: String; the portal URL based on the account type
InviteSummary	Represents an account invitation: who sent it, what was it called, and when it was sent	sender: EmailAddress; who sent the invitation title: String; subject-line of the invitation createDate: java.util.Date; the date the invitation was sent
EmailAddress	Represents an RFC822 email address; e.g. [Joe Bloggs <joe.bloggs@example.com>]. In the example, "Joe Bloggs" is the "personal name" portion of the email address, and "joe.bloggs@example.com" is the "address" portion of the email address.	address: String; the address portion personal: String; the personal name portion ascciQuotedPersonal: String; the personal name portion encoded as ASCII so that it is suitable for use with SMTP servers utfQuotedPersonal: String; the personal name portion quoted so that UTF characters are preserved (if they exists in the name) asciiText: String; the personal name and address portions together, containing only ASCII so that it is mail-safe utfText: String; the personal name and address portions together, with Unicode characters preserved.
FormatMethod	A wrapper around the "java.lang.String.format(String format, Object… args)" method for execution within a template.	Example execution: ${format("%s %s.", "Hello", "world")}

Server Email Templates

Template Name	Template Files	Data Model
Account activation notification – email sent to users who extended an invitation to the user who just activated their account confirmation – email sent to the user who just activated their account	accountactivationnotification.html.ftl accountactivationnotification.subject.ftl accountactivationnotification.text.ftl accountactivationconfirmation.html.ftl accountactivationconfirmation.subject.ftl accountactivationconfirmation.text.ftl	account: AccountSummary invites: List of [InviteSummary] inviteTitleSize: Integer; number of characters of the longest invite title recipientAddressSize: Integer; number of characters in the longest recipient email address recipientPersonalSize: Integer; number of characters in the longest recipient personal name recipientUtfTextSize: Integer; number of characters in the longest recipient personal & address text
Account Appeal Link The email sent to users whose email requires verification for a given action. Such actions include requesting a password reset and new account creation (if email verification is required for newly created accounts). The email contains a link to complete the process.	accountappeallink.html.ftl accountappeallink.subject.ftl accountappeallink.text.ftl	user: Actor; account being accessed url: String; URL to follow to complete process
For password reset requests, this link takes you to the reset password page. Once the user changes the password, either by this link or by logging in and going to the change password page, the Password Changed template is used to format the email to notify the user of the change.
Account Request The email sent to admin users detailing an account request.	accountrequest.html.ftl accountrequest.subject.ftl accountrequest.text.ftl	name: String; requestor’s name address: String; requestor’s email address message_HTML: String; requestor’s message in HTML message_TEXT: String; requestor’s message in plain text portal: String; portal from which request was made
Download Notification Email The email sent to the original sender when the package has been downloaded by a recipient.	downloadnotification.html.ftl downloadnotification.subject.ftl downloadnotification.text.ftl	packageId: String; the package that was accessed filename: String; the document title, or null if the complete package was downloaded recipient: String; who accessed the file, or null for anonymous access downloadDate: Date; when the recipient downloaded the file uploadDate: Date; when the sender sent the package subject: String; subject line from the sender’s email
External User Invitation The email automatically sent to newly created external users inviting them to use the Mail Express system.	externaluserinvitation.html.ftl externaluserinvitation.subject.ftl externaluserinvitation.text.ftl	displayName: String; new account’s display name; may be null dropoffUrl: String; the URL to the drop-off page username: String; new account’s username; same as email address password: String; new account’s password forcePasswordChange: Boolean; whether the new user will have to change the password the first time the account is accessed
Package Upload Portal Send Notification The email sent to recipients of packages sent from the Package Upload Portal.	dropoffsendnotification.html.ftl dropoffsendnotification.subject.ftl dropoffsendnotification.text.ftl dropoffsendnotification.html – minimal.ftl	hasDownload: Boolean; whether the package has attachments hasAccountInvite: Boolean; whether the package has account invitations hasReplyInvite: Boolean; whether the package has reply invitations expiration: java.util.Date; when the package expires; may be null subject: String; subject line from the sender’s email packageLinkOnly: Boolean; whether to include links to all the files in the package individually or only the package-pickup page senderCopy: Boolean; whether the sender wants a copy of the message delivered to the recipients (like a CC) message_HTML: String; sender’s message accompanying the package in HTML message_TEXT: String; sender’s message accompanying the package in plain text sender: EmailAddress; the sender’s email address recipientCount: Integer; the total number of "To" and "Cc" recipients packageLink: String; package access URL attachments: list of [Attachment]s attachmentLengthSize: Integer; number of characters in the longest attachment length and unit attachmentTitleSize: Integer; number of characters in the longest attachment title attachmentLinkSize: Integer; number of characters in the longest attachment link accountLink: String; URL to activate account invitation accountMessage_HTML: String; account invitation message has HTML accountMessage_TEXT: String; account invitation message as ASCII replyAllLink: String; URL to reply to all recipients with uploads replyLink: String; URL to reply to the sender with uploads
Package Upload Send Confirmation The email confirmation sent to the sender detailing the transfer’s files, recipients.	dropoffsendconfirmation.html.ftl dropoffsendconfirmation.subject.ftl dropoffsendconfirmation.text.ftl	accountInvites: Boolean; whether these recipients were sent an account invite or not expiration: Date; when the package expires; may be null identifier: String; the package that was uploaded hasDownload: Boolean; whether the package has attachments hasAccountInvite: Bboolean; whether the package has account invitations hasReplyInvite: Boolean; whether the package has reply invitations recipientsHaveNames: Boolean; whether any of the recipients have a personal name or just email-addresses recipients: list of recipient [EmailAddress]es restricted: list of restricted recipient [EmailAddress]es (links are removed from notification email) recipientAddressSize: Integer; number of characters in the longest recipient email address recipientPersonalSize: Integer; number of characters in the longest recipient personal name recipientUtfTextSize: Integer attachments: list of [Attachment]s attachmentLengthSize: Integer; number of characters in the longest attachment length and unit attachmentTitleSize: Integer; number of characters in the longest attachment title attachmentLinkSize: Integer; number of characters in the longest attachment link
Package Upload URL The email sent via the Administration portal’s Drop-Off Settings page. Used to notify recipients of the Mail Express Server’s Package Upload Page URL.	senddropoffurlinvitation.html.ftl senddropoffurlinvitation.subject.ftl senddropoffurlinvitation.text.ftl	recipient: String; recipient of the invitation dropoffURL: String; the URL to the drop-off page
Password Changed The email sent to users whose password has been changed via the change password link in the web portal.	accountpasswordchanged.html.ftl accountpasswordchanged.subject.ftl accountpasswordchanged.text.ftl	user: Actor; account being accessed internalUser: Boolean; true when user.kind is either InternalAutomatic or InternalManaged, false otherwise date: java.util.Date; when the user changed their password
Store Quota Notification The email sent to admin users when the file store quota or database size quota has been reached.	storenotification.html.ftl storenotification.subject.ftl storenotification.text.ftl	percentFull: Double; ratio of the current size to the quota storeType: String; type of store: FileSystem, Database sizeAmount: Double; current size of the store sizeUnit: String; amount unit: Kb, MB, etc quotaAmount: Double; quota for the store quotaUnit: String; amount unit: Kb, MB, etc
Test Email The test email send when using the test functionality on the Administration portal’s SMTP configuration page.	test.html.ftl test.subject.ftl test.text.ftl	none
Undeliverable Notification The email sent to sender in the event that Mail Express was unable to deliver the message and the reason why; also whenever you receive a delivery status notification update from the mail server.	undeliverablenotification.html.ftl undeliverablenotification.subject.ftl undeliverablenotification.text.ftl	user: Actor; original sender of the failed message subject: String; the subject line of the failed message errors: list of [Problem]s

Outlook Add-In Email Templates

Template Name	Template Files	Data Model
Outlook Add-in Invitation Message The invitation message customized per recipient included in the account invitation email from the Outlook Add-In.	addininvitationtemplate.html.ftl addininvitationtemplate.text.ftl addininvitationtemplate.html – minimal.ftl	sender: EmailAddress; the sender’s email address accountLink: String; "${InvitePageLink}"; this is a fixed token so that the Outlook Add-In can replace it accounts: list of [AccountSummary] userAccountSize: Integer; number of characters in the longest user account userEmailSize: Integer; number of characters in the longest user email userNameSize: Integer; number of characters in the longest user name userPortalSize: Integer; number of characters in the longest user portal userEnabledSize: Integer; number of characters in the longest user enabled state
Outlook Add-in Recipient Header The recipient header customized per recipient included in the email from the Outlook Add-In.	addinrecipienttemplate.html.ftl addinrecipienttemplate.text.ftl addinrecipienttemplate.html – minimal.ftl	subject: String; subject line from the sender’s email toRecipients: list of "TO" recipient [EmailAddress]es ccRecipients: list of "CC" recipient [EmailAddress]es disambiguate: Boolean; whether the package has more than one non-BCC tracking recipient recipientCount: int; the total number of "To" and "Cc" recipients sender: EmailAddress; the sender’s email address replyTo: list of the "TO" recipient [EmailAddress]es with the addition of the sender if he/she is not also a recipient
Outlook Add-In Send Notification The email sent to recipients of packages sent from the Outlook Add-In.)	addinsendtemplate.html.ftl addinsendtemplate.text.ftl addinsendtempalte.html – minimal.ftl	hasDownload: boolean; whether the package has attachments hasAccountInvite: boolean; whether the package has account invitations hasReplyInvite: boolean; whether the package has reply invitations recipientHeader: String; the header token "${RecipientHeader}", or the disambiguation header if it is the same for all recipients, or empty if it is not required expiration: java.util.Date; when the package expires; may be null subject: String; subject line from the sender’s email packageLinkOnly: Boolean; whether to include links to all the files in the package individually or only the package-pickup page packageLink: String; "${PickupPageLink}"; this is a fixed token so that the Outlook Add-In can replace it replyLink: String; "${ReplyPageLink}"; this is a fixed token so that the Outlook Add-In can replace it replyAllLink: String; "${ReplyAllPageLink}"; this is a fixed token so that the Outlook Add-In can replace it accountLink: String; "${InvitePageLink}"; this is a fixed token so that the Outlook Add-In can replace it accountMessage: String; "${InviteMessageTemplate}"; this is a fixed token so that the Outlook Add-In can replace it recipientCount: int; the total number of "To" and "Cc" recipients sender: EmailAddress; the sender’s email address replyTo: list of the "TO" recipient [EmailAddress]es with the addition of the sender if he/she is not also a recipient attachments: list of [Attachment]s (Note: link: String; "${FileLink.#}"; this is a fixed token based on the attachment’s index (#) in the list so that the Outlook Add-In can replace it) attachmentLengthSize: Integer; number of characters in the longest attachment length and unit attachmentTitleSize: Integer; number of characters in the longest attachment title attachmentLinkSize: Integer; number of characters in the longest attachment link

Minimal Header Templates

The "minimal" templates below should all be used together to create a minimal email header. The "minimal" templates are installed in the <Installation Directory>\webapps\ROOT\WEB-INF\template\minimal templates\ folder.

To use a "minimal" template

Rename the standard template (e.g., addinsendtemplate.html.ftl to addinsendtemplate - original.html.ftl).
Copy the "minimal" template into the \template\ folder and then rename the "minimal" template to the original name (e.g., addinsendtemplate.html - minimal.ftl to addinsendtemplate.html.ftl).

To use a translated "minimal" template

(Refer to Localization and Language Support for more information about the localized templates.)

Copy the translated "minimal" template into the \template\ folder.
Rename the translated "minimal" template to the standard, translated name (e.g., addinsendtemplate.html – minimal_de.ftl to addinsendtemplate.html_de.ftl).
Repeat the procedure for each of the translated "minimal" templates.

Each of the renamed templates must be saved in the <Installation Directory>\webapps\ROOT\WEB-INF\template folder.

Template Name	Template Files	Data Model
Package Upload Portal Send Notification - Minimal The email sent to recipients of packages sent from the Package Upload Portal.	dropoffsendnotification.html – minimal.ftl	Refer to description of non-minimal templates above.
Outlook Add-in Invitation Message - Minimal The invitation message customized per recipient included in the account invitation email from the Outlook Add-In.	addininvitationtemplate.html – minimal.ftl	Refer to description of non-minimal templates above.
Outlook Add-in Recipient Header - Minimal The recipient header customized per recipient included in the email from the Outlook Add-In.	addinrecipienttemplate.html – minimal.ftl	Refer to description of non-minimal templates above.
Outlook Add-In Send Notification - Minimal The email sent to recipients of packages sent from the Outlook Add-In.)	addinsendtempalte.html – minimal.ftl	Refer to description of non-minimal templates above.

Minimal header example:

Web Portal Templates

There are six basic types of web portal customizations, described in "1. Template" below.

Each page has a customizable header at the top of the page and footer at the bottom of the page.
In one case, we allow the page's content to be customized.
Pages can be further specialized with an enumerated argument.
Pages can be localized based on the web-viewer (i.e., the computer's language setting).
Only the parts of the Web portals mentioned below are customizable.
The template file's name must have the following format:

custompage[template].[parameter].[location].html_[language]_[country].ftl

1. Template:
  - Account: self-maintenance pages; specialized by "Account template customization"
  - Login: login page; specialized by "Portal type"
  - Home: portal disambiguation page
  - Portal: landing page; specialized by "Portal type"
  - TermsOfService: provides the Terms of Service that external users must agree to before using the system.
  - Misc: (miscellaneous) every other page; specialized by "Portal type"
  - Default: global "catch-all" customizations
2. Parameter (portal or account page changes):
  - Admin
  - External
  - Internal
  - Pickup
  - PasswordChange
  - RequestAccount
  - LostPassword
3. Location:
  - Header
  - Footer (The footer’s data-model only contains specialization parameters of portal-type.)
  - Content
4. The default templates are for "en_US."
  - For details of country-specific codes, refer to the ISO 3166 code lists.
  - For details of language-specific ISO 639-1 codes, refer to the Codes for the Representation of Names of Languages
  - Language
    
    ISO 639-1 code
    
    English
    
    en
    
    German
    
    gem
    
    Spanish
    
    spa
    
    French
    
    fr
    
    Chinese
    
    zh
    
    Turkish
    
    tr
    
    Italian
    
    it
    
    Portuguese
    
    pt

Data model

path: String; path to load image resources
parameter: String; specialization argument
template: String; type of customized template
format: [freemarker.template.TemplateMethodModel]; hook into the String.format(String, Object, …) method

Terms of Service (TOS) Template

In Mail Express v4.0.1, you can require external users to accept a Terms of Service agreement before accessing the external portals. An additional Freemarker template is provided to customize the Terms of Service page (custompageTermsOfService.content.html.ftl).

On the General User Settings page, the administrator must select the Require external users to agree to Terms of Service check box to display the Terms of Service. Their agreement is stored in the Mail Express database, and the account will not be presented with the agreement again.

How Mail Express Uses the Customized Templates

Suppose someone was trying to sign in to the Administrator portal. Mail Express would look for a customized template to render both the header and footer of that page. For the header, below is the order the files would be considered (the footer is similarly processed). Failing to find the first one, Mail Express would look for the second one. Failing that, it would look for the next one, and so on. If no custom header file is found, Mail Express uses the default.

custompagelogin.admin.header.html_en_US.ftl
custompagelogin.admin.header.html_en.ftl
custompagelogin.admin.header.html.ftl
custompagelogin.header.html_en_US.ftl
custompagelogin.header.html_en.ftl
custompagelogin.header.html.ftl
custompagedefault.header.html_en_US.ftl
custompagedefault.header.html_en.ftl
custompagedefault.header.html.ftl

The same data model is used for any template that is found. Administrators can choose any number of files at the appropriate level to meet their specific needs. Footers are processed similarly to headers; the only notable difference is that the footer’s data model only contains specialization parameters of portal-type.

Localization depends on the templates available and the language setting on the client computer. (That is, if you define a Japanese template, but the client computer does not have the Japanese language pack installed, the client computer will not display the Japanese template correctly.)

Misc Templates

Template Files

Data Model

sendattachmenttemplate.html.ftl

The Package Recipient Notification emails that are sent to recipients after a package is sent via either the Outlook Plug-in or the Package Upload Portal will contain a small attached html file. By default this file will contain the list of links to download the files. This template allows for customization of this attached html file.

attachments: list of attachments; properties of interest
title: String; the document title
length: Double; the document size
unit: String; the document unit: Kb, MB, etc
link: String; document access URL

krb5.conf.ftl

Mainly for debugging purposes; allows customization of the Kerberos configuration file used for Kerberos authentication.

kerberosRealm: String; the upper-case version of the Authentication Settings "Domain name" field configured via the Mail Express Server Administration Portal Internal Settings page.
kdcHost: String; the host name or IP Address of the Kerberos Key Distribution Center (e.g. the Active Directory Server) as configured in the Authentication Settings "KDC host" field of the Mail Express Server Administration Portal Internal Settings page.
kdcPort: Integer; the listener port of the Kerberos Key Distribution Center (e.g. the Active Directory Server) as configured in the Authentication Settings "KDC port" field of the Mail Express Server Administration Portal Internal Settings page.
domain: String; the Windows domain name managed by the Kerberos Key Distribution Center (e.g. the Active Directory Server) as configured in the Authentication Settings "Domain name" field of the Mail Express Server Administration Portal Internal Settings page.

Date Format

You can specify the date and time format within the templates that use dates. For example, in the variable ${expiration?datetime?string.long}, you would change long to short, medium, or full:

short—e.g., 11/20/10 12:45 PM
medium—Nov 20, 2010
long—November 20, 2010
full—Wednesday, November 20, 2010

Branding Templates

Branding templates are available in the C:\Program Files\Globalscape\Mail Express\webapps\ROOT\WEB-INF\template directory for adding your own branding to email notifications.

Template Name	Template Files	Editable Content
Package Upload Portal Send Notification Branding	branding.html.ftl	${email} <div style="font-size:9px;">Powered by Globalscape® Mail Express™ </div>
Package Upload Portal Send Notification Branding	branding.rtf.ftl branding.text.ftl	${email} Powered by Globalscape\u00AE Mail Express\u2122
Outlook Add-in Send Notification Branding	addinsendbranding.html.ftl	<div style="font-family:Arial;border:solid 1px #2E62AA;padding:.5em .2em .2em .5em;font-size:13px;margin-bottom:0.8em;"> ${email} <div style="font-size:9px;">Powered by Globalscape® Mail Express™</div> </div>
Outlook Add-in Send Notification Branding	addinsendbranding.rtf.ftl addinsendbranding.text.ftl	${email} Powered by Globalscape\u00AE Mail Express\u2122

Replacing the Mail Express Logo with Your Own

The images subdirectory (by default, <Installation Directory>\webapps\ROOT\WEB-INF\template\images) contains the Mail Express logo and others. You can "brand" Mail Express with your own graphics by overwriting the existing file. HeaderBar.header_logo.png is the header image for all Mail Express pages.

To replace the Mail Express logo with your own

Make a copy of HeaderBar.header_logo.png and then paste it in the same directory. It will be saved as Copy of HeaderBar.header_logo.png.
Create/copy/edit your own logo, making sure it has the same dimensions (310 x 32 pixels) by cropping or resizing it, or use the HeaderBar.header_logo.png as a "template" and paste/create your logo on top of it in your graphic editor.
Save the new logo in the image subdirectory, named HeaderBar.header_logo.png overwriting the existing logo. (You will still have Copy of HeaderBar.header_logo.png if you decide to revert to the original.) Mail Express Server will display your new logo in place of the Mail Express logo.
If you need to go back to the original logo, just rename or delete your logo from the images directory, then rename the original back to HeaderBar.header_logo.png.

It is not necessary to reboot the server to see your changes.

Language	ISO 639-1 code
English	en
German	gem
Spanish	spa
French	fr
Chinese	zh
Turkish	tr
Italian	it
Portuguese	pt