Sending a newsletter from the CMS

What to achieve

Your editors are accustomed to using the CMS to edit contents for your website(s). It makes sense to use the same CMS to edit contents for the newsletter as well (or other emails, for that matter).

Advantages:

Editors do not have to learn to use another editorial system.
Developers can use the same technology to create email newsletters like for the websites.
Editors can share content between websites and newsletter.
The same editor permissions or workflows can be used.

How to achieve it

In order to send a newsletter the following steps must be taken by the CMS:

Generate a newsletter HTML file
Create an XML event file with instructions on how, when, what and to whom the newsletter should be sent.
POST the event file to the UM EventFile REST interface

Details

The first element is the newsletter itself, the HTML file plus images or other attachments. The HTML code will be created by the CMS or your web application which uses your CMS. It however must be compatible to common email clients. You can test compatibility with Litmus (https://www.litmus.com ), an inbox preview integration with the UM is available (https://downloads.universal-messenger.de/knowledge-base/documentation/universal-messenger/html/UM_EN/Developer/Inbox_preview.html).

The UM will send the HTML code basically as is, apart from the following modifications:

Personalization instructions
You can add personalizations instructions within the HTML code or text which will be evaluated by the UM which then modifies the resulting HTML for each recipient. E.g. it is possible to add a personalized salutation (“Dear Mrs Miller”) or add placeholders which will be replaced by an internal UM value like the recipients email address. It is also possible to add a bracket around a content module to hide or show that content based on a condition like “is a member of segment XY”.
For details see: https://downloads.universal-messenger.de/knowledge-base/documentation/universal-messenger/html/UM_EN/Developer/Personalization.html
Tracking
If configured the UM will add a tracking pixel to track whether a recipient has opened the email. The UM then will also rewrite every external link in the email to send it through its link tracker.
For details see: https://downloads.universal-messenger.de/knowledge-base/documentation/universal-messenger/html/UM_EN/Developer/Tracking_configuration.html
Personalized unsubscribe link
In order to allow each recipient to unsubscribe from the newsletter a link can be added to the newsletter, usually in the footer. The link target is a web page which contains a UM newsletter form. It is personalized and will contain a special hash string which helps the UM to identify the recipient.
For details see section “Link generator” on https://downloads.universal-messenger.de/knowledge-base/documentation/universal-messenger/html/UM_EN/Newsletter/Newsletter_App_configuration.html

When sending a newsletter the UM will read this HTML file and send it to the specified recipients. The HTML file can be defined as a URL (to which the UM will need access) or inline in the XML event file (see below) which is sent to the UM web service.

Pictures and Attachments

The newsletter can contain pictures and attachments. Those files can be either referenced as a URL in the HTML or can be sent inline base64 encoded in a <file> tag inside the XML event file. The UM must be able to fetch the images from the URL, if the option to send the images with the email is set.
For details, see section “<file>” on https://downloads.universal-messenger.de/knowledge-base/documentation/universal-messenger/html/UM_EN/Developer/XML_elements_and_attributes.html.

Example HTML file

<html>
  <head><title>Your monthly newsletter</title></head>
  <body>
    <h1>Your monthly newsletter</h1>
    <p>
      <!-- the following code will be replaced by the UM with a personalized salutation -->
      {switch|salut
       |male |Dear Mr {lastname},
       |female |Dear Mrs {lastname},
       |family |Dear family {lastname},
       |company|Dear Sir / Madam,
       |default|Dear Sir / Madam,
      }
      this is the introduction text shown to every recipient.
    </p>
    
    
    <p>
      This section is shown to every recipient.
    </p>
    
    
    {if|inVChannel('region_west')|
    <p>
      This section is only shown to recipients in the segment "region_west".
    </p>
    }
    
    
    <h2>Footer</h2>
    <ul>
      <li><a href="https://yourwebsite/">Visit us on the web</a></li>
      <li><a href="https://yourwebsite/newsletter/?c={msgid}&action=unsubscribe">Unsubscribe via personalized link</a></li>
    </ul>
    
    <!-- this will be replaced by the tracking pixel -->
    {trackerpixel}
  </body>
</html>

XML event file

The event file is in the XML format and contains all instructions on how, what, when and to whom the HTML file generated before will be sent as a newsletter by the UM. This file will be passed as the POST body to a UM web service, so it can be generated “on the fly”.

Usually the event file contains the follow informations which can also be given by CMS editors:

Email subject
Send date (optional if newsletter should not be sent immediately)
Recipient target groups (lists or segments from the UM)
The newsletter HTML code (inline or as URL)
Optional: Files or attachments, inline base64 encoded or as URLs

Example event file:

<event>
  <destination>
    <channel>recipients</channel>
  </destination>
  <data>
    <email obeyPreferHtml="false">
      <subject>Email subject</subject>
      <htmltext embedImages="all" inline="true">
        <![CDATA[
          <html><body>
            ...your newsletter html...
            <img src="logo.png" title="Image from 'inline' attachment, see below"/>
          </body></html>
        ]]>
      </htmltext>
      <!-- Attach file from base64 to be referenced from HTML body -->
      <file name="logo.png" disposition="inline" inline="true">iVBORw0KGgoAAAANSUhEUgA[...]ORK5CYII=</file>
      
      <!-- Attach file from base64 -->
      <file name="invoice.pdf" disposition="attachment" inline="true">J892hhiehdh[...]AAAAASUVORK5CYII=</file>
      
      <!-- Attach file from local path -->
      <file inline="false">/CMS/export/static/gtc.pdf</file>
    </email>
  </data>
</event>

For details see: https://downloads.universal-messenger.de/knowledge-base/documentation/universal-messenger/html/UM_EN/Developer/XML_event_file.html

Universal Messenger EventFile REST interface

The XML event file contains all information necessary for the UM to send a newsletter. To start the delivery the event file must be POSTed to the EventFile REST service as a body. Once it has been posted, the delivery will start immediately (unless a send date in the future is given) and the newsletter will appear in the UM send queue.

Request

URL: <um-rest-url>/de.pinuts.cmsbs.restsend.EventFile/
Parameters:
- open: API Key
Body:
- XML event file
Header:
- Content-Type: text/html; charset=UTF-8

Example request

With curl the request can be tested like this:

curl <um-rest-url>/de.pinuts.cmsbs.restsend.EventFile/?open=<cmsbs.open> --data-binary @eventfile.xml --header "Content-Type: text/xml; charset=UTF-8"

For details see: https://downloads.universal-messenger.de/knowledge-base/documentation/universal-messenger/html/UM_EN/Developer/Passing_the_event_file_via_REST_call.html