Send a Message Series (mail / push / SMS to many customers)

← API Index

A message series is one message to many customers on one channel. It works like a Serienmail: the messages are queued, delivered in the background (throttled, optionally scheduled), personalized per recipient, and counted as one series in the statistics. The call that creates the series returns immediately - it never waits for the delivery.

Channels available through the API: mail, push, sms and auto (the shop picks the best channel per recipient). Mails with attachments are created by the PCG backend as before.

Access

All methods here require an admin session (see use-api): log on with api/logon using an account with admin rights. Other sessions get 401 not_authorized.

Create a series

api/admin/message/series (POST):

The answer (MessageSeriesResult) carries result=queued, members (queued messages) and serieref - keep that reference, it is the key to everything below.

api/admin/pushactiongroup is a shortcut for a push series to one action group (agid, title, message, imageUrl, linkUrl, dryrun) and returns the same serieref.

Choose the mail template

template takes one value, which is one of three kinds of reference:

Value Template Refused when
1 .. 9 the template configured under that number in the admin setup (Mail → Vorlagen, Mailvorlage 1..9) nothing is configured under the number (template_not_configured)
store://<id> a mail template of the shop's file store (made with the template editor), by its file id there is no mail template under the id (template_not_in_store)
https://... an external template page, fetched for the sendout (cached for 10 minutes) longer than 255 characters (template_url_too_long)

Empty or 0 is the standard template. The kinds are told apart by their form only, and nothing is guessed: a bare number above 9 (template_number_not_1_to_9) is not taken as a file id, a store:// without a number (template_store_id), a url with blanks, a fragment or a user:password@ part (template_url), and paths or other schemes such as /mail/x.jsp or ftp://... (template_format) are refused. template with push or sms is refused too (template_needs_mail_channel). The reason comes back as error_reason of a 400 parameter_error with error_field=template.

The reference is checked on a dryrun=1 as well, so a dry run is the way to try one out. That an external page answers and contains the oo:message tag is not checked when the series is created - a mail whose template cannot be fetched or has no place for the text is counted as a send error.

Follow the delivery

stats/mailcampaigns1 lists every series (MailCampaign), newest first; filter with channel=push. Pass sm_infomails=1 to include Infomails - series without a campaign id (the default of a series created here). Per series:

stats/mailopens with sid=<serieref> gives the opens/taps per hour or day, and stats/push1 with serieref=<serieref> lists the individual pushes of the series with their state.

Delivery and tap counts need apps that report back (see setup push notifications); for an external push provider the same applies to the devices it serves.

Cancel a series

api/admin/message/series/cancel (POST, serieref) removes the messages that were not sent yet. Messages already handed to a provider are not recalled; the statistics keep what was sent. Idempotent.

Template tags

Every mail of a mail or auto series (and every other mail the shop sends) is merged into a mail template: a layout frame with header, footer and corporate design, either the built-in one or - named with template - one configured in the admin setup (Mail → Vorlagen), one of the file store or an external HTML page. text becomes the message inside that frame. This chapter is the authoring reference for such a page; it is also what api/system/checktemplate?templatesuffix=<slot> (admin session) validates when it reports hasPlaceholder.

The template tags are not text variables but XML-style elements in the template HTML, all in the oo: namespace. The sendout processes them one tag name at a time on the raw template string, without an HTML parser, so the rules below are purely textual.

Recognised syntax per tag:

Processing rules:

Tag reference

The markup as it appears in a template and what the sendout turns it into:

oo:message — the (personalized) mail text, once per template. Both forms are equivalent:

<oo:message>Hier steht später der Text der E-Mail.</oo:message>
<oo:message/>

oo:subject — the mail subject, once per template:

<h1><oo:subject/></h1>

oo:link — the shop's home URL (the "HomeUrl" of the basic settings), every occurrence:

<a href="<oo:link/>">Zum Shop</a>

oo:unsubscribe with oo:unsubscribe_link — the unsubscribe footer. The container marks the whole block, the link tag inside it marks where the URL goes:

<oo:unsubscribe>
  <p style="font-size:10px">
    Sie möchten keine Newsletter mehr?
    <a href="<oo:unsubscribe_link/>">Hier abmelden</a>
  </p>
</oo:unsubscribe>

With an unsubscribe link (newsletter / ad mails) only oo:unsubscribe_link is replaced; the container tags stay in the HTML as inert unknown tags, so the mail client renders the block:

<oo:unsubscribe>
  <p style="font-size:10px">
    Sie möchten keine Newsletter mehr?
    <a href="https://shop.example.de/unsubscribe.jsp?code=…">Hier abmelden</a>
  </p>
</oo:unsubscribe>

The URL is the shop's configured unsubscribe page (the code is appended as oo-unsubscribe=…) or, if none is configured, <shop domain>/unsubscribe.jsp?code=….

Without an unsubscribe link (transaction/system mails) the whole container disappears, including its content:

<!-- nothing is left of the block, not even its inner text -->

The link tag belongs inside the container. A bare <oo:unsubscribe_link/> outside it is replaced by empty text when there is no link, which leaves an empty href behind.

oo:read with oo:read_link — the "read online" block, same pattern:

<oo:read>
  <p>Wird die E-Mail nicht richtig angezeigt?
    <a href="<oo:read_link/>">Im Browser öffnen</a>
  </p>
</oo:read>

For a series mail oo:read_link becomes <shop domain>/readonline/<token> and the container stays. For a non-series mail, and when the read-online page itself is rendered, every oo:read container is removed with its content.

oo:track — the tracking pixel:

<oo:track/>

With tracking on this becomes <img height="1" width="1" src="<shop domain>/oo-mail.gif?trc=…"/>; if the tag is missing it is injected right before </body>. With tracking off the tag is removed.

oo:content — includes an article (Textbaustein, a text block maintained in the shop admin) rendered to HTML, every occurrence. st is the article's search term / short name and must directly follow the tag name; a missing st is a configuration error:

<oo:content st="mailfooter"/>
<oo:content st="mailfooter">Hier erscheint der Textbaustein "mailfooter".</oo:content>

Legacy marker <shop:message/>

The pre-oo: form of the message placeholder. It is a plain string replacement without container semantics: every literal occurrence is replaced by the message text, there is no end tag and no encoded variant. If a template contains it, oo:message is not looked for at all. The built-in default templates still use it; new external templates should use oo:message.

Don't forget

Ideas

Getting started

# logon (admin account)
GET  <base>/api/logon4?cid=<admin>&pass=<password>

# how many recipients?
POST <base>/api/admin/message/series?oo-rf=json   channel=push&agid=40&dryrun=1

# queue it
POST <base>/api/admin/message/series?oo-rf=json   channel=push&agid=40&title=Neu im Sortiment&text=Hallo %vorname%, ...&link=https://shop.example.de/?p=item&id=123

# follow it
GET  <base>/api/stats/mailcampaigns1?channel=push&sm_infomails=1&oo-rf=json
GET  <base>/api/stats/push1?serieref=<serieref>&oo-rf=json

# stop the rest
POST <base>/api/admin/message/series/cancel?oo-rf=json   serieref=<serieref>