Messaging
Table of contents
CloudBilling offers a flexible messaging solution. This entails the possibility to automatically send emails to customers with transformation results as attachments. Mails can be sent out in bulk this way.
To complete a messaging run successfully, a few items need to be configured prior:
- Body templates
- Subject templates
- Email addresses for all the customers you want to send emails to
- Sender email addresses
- SMTP settings
- Message definitions
The messaging settings can be found under “Administration” (cogwheel), as can be seen in Figure Messaging 1.
Figure Messaging 1: Messaging options in Administration menu
Body Templates
A message body template is used to transform the content of the email. It very much resembles a transformation template and is, therefore, often created and maintained by a CloudBilling consultant. The output for a message template can either be HTML or plain text. A message template is customizable and can use customer information, invoice information, and images, to name a few.
Subject Templates
A subject template is used to transform the subject of the email. Similar to body templates is customizable and can use customer information, invoice information and so on. The output for a subject template can only be one line of text.
Recipient Keys
You can configure a number of recipient keys. These keys will be used both to configure a message template and an entry in a customer collection of email addresses. In order for a customer to receive an email for a particular message definition, the message definition, the collection of email addresses for that customer must contain at least one entry that matches the recipient key configured in the message definition.
A recipient key consist of:
- Key: An identifier for the email address that can be used to refer to the email address.
- Display Name: The name that will be displayed when selecting this key, both when editing message definitions and customer information.
Sender Email Addresses
A set of email addresses can be added in this section. These email addresses can be used in the message definition to determine what email address should be used to send the emails from.
A sender profile consist of:
- Key: A unique ID of the email address that can be used to refer to the email address.
- Email: The email address.
- Display Name: The name that will be displayed when receiving an email from this address.
SMTP Settings
The SMTP settings must be set up, usually, only once. These settings allow for an SMTP server to be defined as well as a set of email addresses from which messages can be sent (Figure Messaging 2). The following fields must be used to define an SMTP server connection:
- Host: the hostname of the SMTP server.
- Port: the port number of the SMTP server.
- Username: optional username to authenticate towards the SMTP server with.
- Password: optional password to authenticate towards the SMTP server with.
- Secure: Require SSL tick box determines whether the connection to the SMTP server must use SSL. This only applies to Explicit TLS.
- We support both Implicit TLS (SSL/TLS) and Explicit TLS (STARTTLS).
- To use Implicit TLS use port 465
- To use Explicit TLS check “Require SSL”.
- We support both Implicit TLS (SSL/TLS) and Explicit TLS (STARTTLS).
- Rate limit (msg/min): outbound message rate limit in messages per minute, used to prevent flooding the SMTP server.
Figure Messaging 2: SMTP Server Settings screen
The sender profiles can be edited on this section too.
Use the test functionality before saving your settings, to determine if they are correct. A successful test sends a predefined test email message, from one of the configured sender email addresses to itself.
Message definitions
The Message Definitions page, as shown in Figure Messaging 3, allows the configuration of Message Definitions. A message definition is a generic description of a message run. Often, it is set up by the CloudBilling consultant. However, this section will provide documentation on how to set up a message definition yourself.
Figure Messaging 3: Message Definitions screen
On the message definitions list page, a new message definition can be added by using the [Add] button in the right top. The table shows the settings of the message definitions. To the right side of the table, there are three buttons that can be used to respectively, edit the message definition, or delete the message definition. With the tick box in the rightmost column, message definitions can be multi-selected to delete multiple definitions at once with the delete button in the header of the table.
Editing or adding a message definition will bring the user to the Edit Message Definition or Add Message Definition page respectively. For the example in Figure Messaging 4, the Edit Message Definition page is shown since this page shows a filled-out message definition. A message definition needs the following fields:
- Name: An identifying name for the message definition.
- From: A choice of one of the sender profiles already defined in sender profiles page or SMTP settings, that the emails will be sent from.
- To: A choice of one of the recipient keys already defined in the recipient keys page.
- Subject Template: The template used as email subject.
- Body template (html): The message template that will be used to generate the html version of the email.
- Body template (plain text): The message template that will be used to generate the text version of the email.
- Transformations: A set of invoice transformations, the result of which will be added to each email as attachments.
Figure Messaging 4: Edit Message Definition screen, example
Additionally, in the Attachments section, if you choose to compress the attachments, a zip archive will be created and you can also choose a password to protect this zip file.
Messaging
Once the Message templates, SMTP settings and Message Definitions are set-up, messages for that definition can be sent. A message run can be started by selecting invoices in the invoices list screen and clicking the “E-mail” button, as shown in Figure Messaging 8.
A popup will appear for you to select the message definition you want to use for this batch of emails. As soon as a message definition was chosen we can perform some checks against the select invoices to make sure the operation will complete successfully. Figure Messaging 9. These checks include:
- existence of the required email address (required by the chosen massage definition) for the customers associated with the selected invoices
- warnings about sending invoices that have not been approved
- warnings about sending invoices that were previously included in message runs
After reviewing your selection, click Send to start sending emails. With this, we will trigger generation of the required transformation results and a message run will be created. The message run will be already started. Our background workers will process the transformation results and, if this operation succeeds in the next 24 hours, the e-mails will be sent. After 24 hours the background workers will stop sending the e-mails in this message run, but you can manually retry sending the faulty messages after this.
Figure Messaging 8: Select invoices for e-mail
Figure Messaging 9: Messaging checks
Message Runs
Once a message run is successfully created, you will be redirected to its overview page as shown in Figure Messaging 6. This page will display information on the message run, including the message definition, current status, transformation from and to date, customer cluster, created date and Bcc email addresses. To the right of the page the overall message result counts can be seen and a [Start] and [Stop] button can be used to respectively start or stop the message run. The number next to the status of message results is clickable and will redirect the user to the overview of all messages used in that message run.
Figure Messaging 6: Message Run overview screen
The Message Results page (Figure Messaging 7) shows an overview of all messages in the message run. On this page, it is important to check whether customers do not appear multiple times in the list, as they will then receive multiple emails, individual results can be removed with the Delete button. In the Message Results lines, there is also a [Send Again] button which can be used to try to send the message again, for example when the message failed to send before due to a faulty invoice transformation. Like before, the rightmost column can be used to multi-select results and delete or resend the selected results bulk.
Figure Messaging 7: Message Results screen
In the header of the Message Results, there are search options available. The search options allow to search on customers, used message definitions and the status of the message. The status of the message can be one of the following:
- Waiting: the message is in an active message run that is paused, and has not been sent yet.
- Pending: the message is waiting to move to the processing status.
- Processing: the message is currently in the process of being sent.
- RecipientKeyNotFound: the customer is missing the required email address.
- UnknownSenderProfile: the message definition configuration points to an unknown sender profile.
- TransformationResultNotReady: transformation results are in processing state.
- GenerateFailed: the message has not been sent, because something went wrong in the generation of the message.
- SendFailed: the message was generated but the sending of the message failed.
- SendRetryExceeded: the message run or user tried to send the message multiple times, which exceeded the limit.
- Error: the message generation concluded in an error; this often has to do with the message template.
- SendSuccessful: the message was successfully sent to the customer.
- Closed: the message was closed manually, and the status cannot be viewed anymore.
Messages that have another status than “SendSuccessful” after the message run is finished, should be investigated further by using the message results page. The common causes of messages not being able to send are the email on a customer missing, the invoice transformation does not exist or failed to be processed or faulty credentials for SMTP server. The Step by step for the message run can be found in Performing a Message run
Once all messages have been send successfully, the invoice message run should be closed with the [Stop] button. When a message run is not closed, it might cause unexpected issues, especially if there might be mails that did not receive the status send successful.
When a message run is finished, ensure to Close the message run by using the [Stop] button, to prevent unexpected issues.