Mailouts

A Mailout allows you to send an email message to multiple recipients at once. It’s commonly used for maintenance notifications, or any other communication that needs to reach your users quickly and efficiently.

Creating a Mailout

Navigate to Mailouts in the admin menu (System -> Mailouts) and click the Create tab to reveal the main mailout form.

info

VirtFusion includes several ready to use templates. You can easily select one from the Predefined Templates dropdown menu.

The following options are available when creating a Mailout:

• Subject This field is required and should contain the subject line of the email. You can use any available variables in the subject, but please avoid using the *_server_list variable.
• Preview Text This field is optional and should contain a short snippet of text. Most email clients use this as a glimpse of the email's content before it's opened.
• HTML This field holds the HTML body of the email. You should avoid entering raw HTML directly, as it uses * Markdown* syntax to automatically generate the HTML when the email is sent.
• Text This field is used for plain text email delivery. It also serves as the text only version of the email when sending HTML emails (optional), ensuring compatibility with email clients that do not support HTML.
• Predefined Templates All your predefined templates and example templates.
• Recipients This will open a popup where you can choose the recipients for the mailout.
• Reference ID An optional reference string that can help recipients identify related Mailouts, especially when multiple messages are sent as part of the same incident.
• Date #1 (UTC) An optional date that will be passed to the {{ utc_date_1 }} variable.
• Date #2 (UTC) An optional date that will be passed to the {{ utc_date_2 }} variable.
• Custom #1 An optional value for the {{ custom_1 }} variable.
• Custom #2 An optional value for the {{ custom_2 }} variable.
• Custom #3 An optional value for the {{ custom_3 }} variable.

Fill in all the relevant fields for your Mailout or select a predefined template.

For more information on variables, please see the Variable Reference

Once you have filled in all the fields, you can either save it as a template for later (Save as Template button in the bottom bar) or preview it before sending by clicking the Preview button in the top bar. It will render the email and pre-fill the variables.

Important Tip!

It's always a good idea to preview a mailout before sending. While you can stop a mailout after it starts, some emails may already be delivered before you realise you have made a mistake.

Selecting Recipients

To select recipients, click the orange outlined Select Recipients button to open the popup.

The following Recipient Types are available:

• Hypervisors & Groups The mailout will be sent to all users who have at least one server on the selected hypervisors and groups. If a user has multiple servers across the selected targets, they will receive only one email.
• All Users The mailout will be sent to all users on the system based on a criteria selection.
• Selected Users The mailout will be sent to all selected users.

Most of the Recipient Types will allow you to select options. For example the Hypervisors & Groups will allow you to select multiple hypervisors and hypervisor groups.

After selecting your options, a button will appear allowing you to calculate the number of recipients the mailout will reach.

When you are happy with the selection. Click the Done button.

Sending the Mailout

Review your selected recipients and preview the mailout one final time. When you're ready, click the Send button in the bottom bar. A confirmation popup will appear to confirm that you want to proceed.

Don't see a Send Button?

If the Send button is not visible, it’s likely that you haven’t selected any recipients or email has not been configured in general settings.

Managing Mailouts

Stopping a Mailout

If you need to stop a Mailout in progress, click the pause icon in the Mailouts list. This option is only visible when a Mailout is actively being sent.

Starting a Previously Stalled Mailout

If a Mailout has been stopped, stalled, or encountered failed email deliveries, you can restart it by clicking the play icon in the Mailouts list.

info

The system ensures that each email is only sent once per Mailout. If any emails fail to send, only those specific ones will be retried.

Viewing the Mailout Progress

Each Mailout shows its progress with a percentage bar while sending. To view the status of individual emails, click the log icon in the Mailouts list.

Mailout Settings

Mailouts have a limited number of configurable settings via the Settings tab, each of which is explained in detail below.

• Enable Logging All emails sent through VirtFusion, including Mailouts, are logged under Logging -> Email. If you prefer not to log Mailouts, you can disable this by toggling the setting off.
• Send Throttling The system will pause for the specified duration between sending each email. This helps accommodate SMTP services with strict sending limits.

Variable Reference

The following variables are available in all Mailout types.

Variable	Description
{{ html_server_list }}	List of servers associated to a user based on the recipient selection. This variable should only be used in the HTML section.
{{ html_server_list_ip }}	List of servers (including the main IP) associated to a user based on the recipient selection. This variable should only be used in the HTML section.
{{ html_server_list_ul }}	Unordered (ul) list of servers associated to a user based on the recipient selection. This variable should only be used in the HTML section.
{{ html_server_list_ip_ul }}	Unordered (ul) list of servers (including the main IP) associated to a user based on the recipient selection. This variable should only be used in the HTML section.
{{ text_server_list }}	List of servers associated to a user based on the recipient selection. This variable should only be used in the TEXT section.
{{ text_server_list_ip }}	List of servers associated to a user (including the main IP) based on the recipient selection. This variable should only be used in the TEXT section.
{{ reference_id }}	Value of the Reference ID field.
{{ custom_1 }}	Value of the Custom #1 field.
{{ custom_2 }}	Value of the Custom #2 field.
{{ custom_3 }}	Value of the Custom #3 field.
{{ utc_date_1 }}	Value of the Date #1 (UTC) field.
{{ utc_date_2 }}	Value of the Date #2 (UTC) field.
{{ utc_date_1_to_user_timezone }}	Value of the Date #1 (UTC) field converted to the recipients timezone.
{{ utc_date_2_to_user_timezone }}	Value of the Date #2 (UTC) field converted to the recipients timezone.
{{ user_name }}	Recipients full name.
{{ user_email }}	Recipients email address.
{{ user_time_now_timezone }}	Time now based on users specified timezone. i.e Sunday 6 April 21:38:13 BST 2025.
{{ system_company_name }}	Company name as specified in general settings.
{{ system_domain }}	Domain of the control server.
{{ system_url }}	URL of the control server.
{{ system_company_web_url }}	Website link as specified in general settings.
{{ system_company_tos_url }}	Terms of service link as specified in general settings.

Webhooks

There are two available Webhook Events for Mailouts. system.mailout & system.mailout.recipient

For more information, see the Webhook documentation.