Mass Mailing

Overview#

The Mass Mailing feature lets you email users in bulk from the SolusVM 2 admin area. For example, you can announce planned maintenance on a Compute Resource. SolusVM 2 emails every user who owns a VM on the Compute Resources that you select. You can also add individual users as recipients.

Mass Mailing provides a template for mailing your users. Each user gets a personalized email from the template. The email lists the user’s VMs on the selected Compute Resources, along with the VM names, IP addresses, and statuses.

Before you start#

Complete these checks before you send a mass mailing:

• Configure outgoing mail. Go to Settings > Mail, enter the SMTP server details, and select Enabled. To check the settings, select Send test email, enter an email address, and click Save.
• Check your permissions. You need the mass mail users permission to preview or send emails. The Admin role has this permission by default. To let other users use Mass Mailing, add this permission to their role in Access > Roles.
  • You can cancel a mailing in Tasks if you have the manage tasks permission.

Sending a mass mailing#

To send a mass mailing, click Mass Mailing in the main menu. Then, select your recipients, write your message, preview, and send it.

Choosing recipients#

Choose one or both of these options:

• Select Compute Resources — Every user who owns at least one VM on a selected Compute Resource receives the email. Click Select all Compute Resources to select every Compute Resource at once.
• Select additional recipients — Add specific users by email address, whether or not they own VMs on the selected Compute Resources.

SolusVM 2 determines recipients with these rules:

• Each user receives one email, even if the user owns VMs on several selected Compute Resources or is also an additional recipient.
• Project members who have access to another user’s VM do not receive the email unless you add them as additional recipients.
• Owners of stopped, suspended, and unavailable VMs receive the email. SolusVM 2 ignores deleted VMs.
• Locked and suspended users receive the email.
• If an administrator owns a VM on a selected Compute Resource, the administrator also receives the email.
• SolusVM 2 sends each message to the email address of the user’s account.

Writing the message#

When you write a mass mailing, you must include a subject and a message body. You can also use template variables in both the subject and message body.

Subject#

The subject is required and is a single line of text. You can use the {{ email }} and {{ vm_count }} recipient-level template variables in the subject, for example, Planned maintenance for {{ vm_count }} of your servers.

Message#

Write the message in HTML. SolusVM 2 sends the HTML that you type as is.

To start from the built-in example:

1. Click Show an example under the Message text box.
2. Click Add example to the Message field. If the text box already has content, SolusVM 2 adds the example to the end of it.
3. Edit the text to fit your message.

Template variables#

Mass Mailing uses Twig template variables to insert per-recipient data. The editor highlights HTML and Twig syntax.

SolusVM 2 supports only a limited subset of Twig variables. It rejects templates that use any variables outside this subset, and it shows an error that explains the problem. To see the supported template variables and their descriptions, click Template Variables next to the Message text box. Click a variable to copy it.

Compute Resource variables work inside a {% for cr in crs %} ... {% endfor %} loop. This loop goes through each of the selected Compute Resources in alphabetical order.

VM variables work through a {% for vm in cr.vms %} ... {% endfor %} loop inside the Compute Resource loop. This nested loop goes through the VMs of the recipient on that Compute Resource. SolusVM 2 sorts them by name and only shows the recipient’s VMs.

VM status#

Keep these points in mind if you use the {{ vm.status }} template variable:

• The status of this variable is the last state that SolusVM 2 observed for the VM. If a Compute Resource becomes unreachable, SolusVM 2 marks all of its VMs as unavailable. In this case, the {{ vm.status }} variable shows the last known status of each VM. The variable shows unavailable only when SolusVM 2 has no previous status for the VM.
• Variable values are lowercase and in English. To change the capitalization, use a filter, for example, {{ vm.status|capitalize }}. To use other wording, use an if condition, for example, {% if vm.status == 'started' %}Running{% endif %}.
• Suspension does not change the status. A suspended VM that is running shows started.

Previewing the email#

Before you send, click Preview to see the email as a recipient would see it. Previewing does not send or queue any email.

By default, the preview uses the data for the first recipient of the current selection. To see the email as another recipient would see it, enter the recipient’s address in the Preview recipient field. The address does not need to be one of the selected recipients. If the selection has no recipients yet, the preview uses sample data and shows a note about it.

If the template has an error, the preview shows it so you can fix the template before you send.

Each recipient gets their own version of the email. Preview the email for at least two kinds of users:

• A user with VMs on several selected Compute Resources.
• A user with no VMs, such as an additional recipient. This checks the parts of the template that handle an empty VM list.

Sending the emails#

To send the emails:

1. Click Send Emails. SolusVM 2 validates the template and creates a task, and a success message appears.
2. Wait for sending to start. It starts two minutes after you click Send Emails. This delay gives you time to cancel a mailing if you sent it by mistake.
3. To track the mailing, go to Tasks and find the task with the mass-mail-users action. The task progress shows the share of recipients that SolusVM 2 has processed.

Cancelling a mailing#

You can cancel a mailing during the two-minute delay before it sends. To cancel the mailing, go to Tasks and cancel the mass-mail-users task. After sending starts, you cannot cancel the mailing.

Handling a failed mailing#

If an error occurs while SolusVM 2 is sending the emails, the task stops and shows the failed status. The task details show the error message. Recipients that SolusVM 2 processed before the failure have already received the email. Take this into account before you send the same mailing again.

Limitations#

Mass Mailing has these limitations: