Send a Message Series (mail / push / SMS to many customers)
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):
channel-push(default),mail,sms, orauto: the shop's "Automatischer Kanal" setting decides per recipient. It is an expression such asmail+push(deliver on both) ormail>push>sms(the next channel only when the previous one cannot reach the customer: no app user, no valid address, no mobile number, or switched off by the customer for campaigns). The statistics show the split insent_mail,sent_push,sent_sms; a recipient reached on two channels counts once intotal.- recipients, exactly one of:
agid(every member of an action group),all=1(every customer),cids(comma-separated customer ids). Blocked customers are skipped automatically. title(mail, push and auto) - the mail's subject and the notification's titletext- the message; both may contain%Variable%placeholders (customer name, next delivery date, ...) which are filled per recipient. The available variables and their groups are listed byapi/system/variables. Formailandauto,textis the mail body (HTML allowed); the mail is wrapped into a mail template (see Template tags below).template- optional, formailandauto: the mail template of the series, see Choose the mail template. Without it the standard template is used.shorttext- short plain text for push and SMS (max 1000 characters). Without it those channels usetextwith the HTML stripped; withautoyou should always give one, so the mail body and the notification text can differ.link- optional; for push it is the deep link opened on tap. It is rewritten to a tracked redirect, so clicks show up in the statistics.image- optional image url (push)senddate- optional start,yyyy-MM-dd HH:mmin the shop's local time; default: as soon as possiblecampaignid- optional; a value > 0 marks the series as marketing: customers without ad permission, and customers who switched this channel off in their newsletter notification setting, are skipped (counted as send errors), and the series appears under that campaign in stats/campaign1. Without a campaign id (or with 0) the series is an Infomail: business information without advertisement, which goes to every recipient.dryrun=1- only count the recipients, queue nothing
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:
total- messages processed so far,duration = 0while the series is still runningsenderrors- messages no channel accepted (no registered device, no mobile number, no ad permission, provider error)delivered- push delivery receipts reported by the appuniqueopens/opens- notification taps (once per push / every report)clicks/unique_clicks- clicks on the tracked link
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:
- Container:
<oo:message>Hier steht später die Nachricht</oo:message>— the whole element, from<oo:xto the end of</oo:x>, is replaced by the system-provided text. The inner content is only sample text for the template author and is always discarded. - Empty element:
<oo:message/>or<oo:message />. - HTML-encoded form:
<oo:message>…</oo:message>/<oo:message/>, so templates saved by a WYSIWYG editor that escapes unknown tags still work. - Attributes are tolerated on every tag but only read by
oo:content(st="…", see below).
Processing rules:
- Each occurrence is matched from its start tag to the matching end tag. Nested tags of the same name are counted, so the outer element is replaced as a whole (a WYSIWYG editor may wrap a container typed into a text block into another one); raw and encoded tags may be mixed.
- Only a start tag counts as an occurrence. A bare mention of the name, a leftover end tag or a
longer tag sharing the prefix (
oo:unsubscribe_linkis notoo:unsubscribe) is left alone. - "Replace with empty text" is how a tag is removed: the element and everything inside it vanish
from the mail. This is used for
oo:unsubscribe,oo:readandoo:trackwhen they do not apply. - A start tag without a matching end tag is a configuration error: the mail is not sent, and the error is logged in the shop log.
- A template without
oo:messageis tolerated with a warning and the mail is sent without the message text (an external template may deliberately be a self-contained reminder/change mail). All other tags are optional; they are only processed when present. - Processing order:
oo:message→oo:unsubscribe/oo:unsubscribe_link→oo:link→oo:read/oo:read_link→oo:subject→oo:track→oo:content. The inserted message text has already been personalized (%Variable%); the template HTML itself is not.
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
- Ad permission and channel opt-in. Use
campaignidfor anything promotional; the series then respects the customers' ad permission and their per-channel newsletter setting. An Infomail - business information (delivery moved, shop closed on a holiday) - goes without one. It reaches every member, so keep it to what a customer would expect. - Push needs a device. Customers who do not use the app, or without a registered device
(or, with an external push provider, unknown to it), end up as
senderrors. Usedryrun=1and stats/pushdevices1 to estimate the reach before sending. - Throughput. Delivery is throttled per tenant and channel (the same hourly limit as for
mail). A series to thousands of customers takes accordingly long; plan the
senddate. - Personalization placeholders that cannot be resolved for a recipient stay empty; test
with
cids=<your own id>first. - One series per intent. Do not queue the same text twice "to be sure": every queued row is delivered; there is no de-duplication across series.
Ideas
- Reminder campaigns per interest. Fill action groups from newsletter clicks (see actiongroups) and push only those groups a new offer matches.
- Delivery-day notices. A scheduled SMS series (
senddate) to the customers of tomorrow's tour, usingcidsfrom your tour planning. - Compare channels. Send the same offer as mail (PCG) and push (here) with the same
campaignidand compare open and click rates in stats/campaign1.
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>