Sending a newsletter from the CMS

Owned by Timo Fuchs
Last updated: Juli 08, 2024 by Florian Wolff
5 min read

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

Newsletter HTML file

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:

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.

See also REST API doc

Request

Example request

With curl the request can be tested like this:

curl -X POST <um-rest-url>/de.pinuts.cmsbs.restsend.EventFile/index -u <api-key>:<secret-key> --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