Overview

The middleware sends various notification emails (calendar invitations, share notifications, reminders, etc.). This page explains the two ways of customizing them and lists every template that exists.

Two ways to customize

There are two independent customization mechanisms. Most tenants need both.

Per-host styling via as-config.yml (recommended for branding)

Button colors, footer text, and a footer image can be configured per host in /opt/open-xchange/etc/as-config.yml under the notificationMails key. The same settings apply to every notification email sent for that host — calendar invitations, calendar reminders, share notifications, deputy grants, GDPR export mails, scheduled-mail failure notices, and onboarding profile mails.

Minimum example:

host3.mycloud.net:
    host: host3.mycloud.net
    notificationMails:
        # mandatory — all three keys must be present
        button:
            textColor: '#000000'
            backgroundColor: '#ffffff'
            borderColor: '#000000'
        # optional — omit the footer: block to suppress it entirely
        footer:
            image: 'custom_logo.png'   # file under /opt/open-xchange/templates/
            text: 'Footer text for host3'

Notes:

• Keyed by host: (or hostRegex:), so different tenants on different hostnames get different colors / footer automatically.
• If you define notificationMails you must provide all three button colors, otherwise the server falls back to the defaults from as-config-defaults.yml and logs a warning.
• footer.image is the filename (not path) of an image that must exist under com.openexchange.templating.path (/opt/open-xchange/templates/).
• This mechanism is style-only. It cannot change wording, structure, or which template file is used.

See custom_host_configuration.md for the full as-config.yml reference.

Global template-file replacement at com.openexchange.templating.path

For anything the notificationMails block can't express — wording, layout, added/removed blocks, additional images — edit the underlying *.tmpl file.

To customize an email, edit the corresponding *.tmpl file in that directory (or place a replacement with the same filename). Changes are picked up on the next mail without a restart.

This is a server-wide change: the template path is not host-aware and not config-cascade-aware, so every host served by that middleware node uses the same template file. Different template files per tenant are not supported.

Before editing: - Keep a backup of the original. - Do not remove or rename placeholders like ${...} — they are replaced with actual content at send time. - If both an .html.tmpl and a .txt.tmpl exist, update both so HTML and plain-text recipients see the same wording. - Roll the edited file out to every middleware node — each node reads its own local copy. - Send a test mail to verify the result.

Email templates by feature

Calendar — invitations and replies

Sent when calendar events are created, updated, cancelled, forwarded, or when a participant replies. Each has an HTML and a plain-text version.

Shared fragments included by the above (edit these to change the look of all calendar mails at once):

• notify.appointment.intro.html.tmpl — intro / header block
• notify.appointment.show.html.tmpl / .txt.tmpl — full event details
• notify.appointment.show.mini.html.tmpl / .txt.tmpl — compact event details
• notify.appointment.styles.css.tmpl — inline CSS

Calendar — reminder mails

• notify.mail.alarm.mail.html.tmpl / .txt.tmpl — reminder email for events with a mail alarm
• notify.mail.alarm.show.html.tmpl — event-details block inside the reminder

Sharing

• notify.share.create.mail.html.tmpl — share / link created, sent to the recipient
• notify.share.pwreset.confirm.mail.html.tmpl — guest password-reset confirmation
• notify.share.compose.prefix.html.tmpl — text inserted above the body when sending a shared file via the composer

Deputy permissions

• notify.deputy.permission.mail.html.tmpl — sent when a user is granted deputy permissions

GDPR data export

• notify.gdpr.dataexport.mail.html.tmpl — sent when a data export is ready to download

Scheduled mail

• notify.scheduled.mail.html.tmpl — sent to the user when a scheduled mail could not be delivered (see scheduled_mail.md)

Client onboarding

• notify.onboarding.profile.mail.html.tmpl — delivers a client configuration / provisioning profile to the user

Common (shared by most notification mails)

Editing these changes every notification email that includes them:

• notify.common.button.tmpl — the styled call-to-action button
• notify.common.footer.html.tmpl — the footer block

Not email templates

These *.tmpl files also live under template directories but are not emails; do not confuse them with the above:

• saml.logout.response.html.tmpl — SAML logout page
• iPhoneTemplate.tmpl, winMobileTemplate.tmpl — device provisioning profiles
• oxdrive_update.tmpl — OX Drive Windows client update descriptor