try out ↗

← API Index


/api/admin/message/series

Queue a message series: one message to many customers on one channel (mail, push, sms, or auto = best channel per recipient). Admin only. Returns immediately with the series reference; delivery runs in the background (throttled, optionally scheduled), the text is personalized per recipient (%Variable% placeholders), links are tracked, and the series shows up in stats/mailcampaigns1 like a Serienmail. Recipients: exactly one of agid, all or cids. A mail can name its template; mails with attachments keep coming from PCG.

Parameters

Name Description Type
channel delivery channel: push (default), mail, sms, or auto = decided per recipient by the shop setting Automatischer Kanal (an expression like mail+push = both, or mail>push>sms = fallback chain), respecting reachability and, for campaigns, the customer's newsletter channel setting string
template mail template, for channel mail or auto only; one of three kinds of reference: a number 1..9 = the template configured under that number in the setup (Mailvorlage 1..9); store:// = a mail template of the file store, by its file id; an absolute http(s) url = an external template page (max 255 characters, 60 on a shop whose mail queue is not migrated yet). Empty or 0 = the standard template. Other numbers, paths and schemes are refused. Checked on a dryrun too string
agid recipients: every member of this action group int
all recipients: every unblocked customer (true/1) bool
cids recipients: comma-separated customer ids (blocked/unknown ids are dropped) string
title mail subject and notification title (mail, push, auto: required unless dryrun, max 200 characters) string
text message text (required unless dryrun, max 10000 characters, %Variable% placeholders allowed); the mail body for mail and auto, and the push/sms text unless shorttext is given (HTML is stripped then) string
shorttext short plain text for push/sms (max 1000 characters); recommended for auto so the mail body and the push text can differ string
link optional link (push deep link), rewritten to a tracked redirect for click statistics string
image optional image url (push) string
senddate optional scheduled start, format yyyy-MM-dd HH:mm (shop local time); default: as soon as possible string
campaignid optional campaign id; > 0 marks a marketing message (customer ad permission is checked, campaign stats via stats/campaign1); without one (or 0) the series is an Infomail: no advertisement, goes to every recipient int
dryrun if true, only count the recipients and queue nothing (result 'dryrun') bool
oo-rf optionally define the response-format for this call. One of: compact (default) | compacts | full | fulls | json | md | html | js | openapi | yaml String
oo-auth optionally force the API to check against the role (instead of silently not returning data). For guests or public access, the default is -1. 0 (regular customer) and above define the role for which the current session is expected to be authorized. int

Error Responses

HTTP Status Error Code Description
401 not_authorized Caller is not an admin
400 parameter_error channel unsupported, recipient selection missing/ambiguous/empty, title/text missing or too long, senddate malformed (detail in error_field:error_reason). error_field template has an error_reason: template_format (none of the three kinds), template_number_not_1_to_9, template_store_id (store:// without a file id), template_url (not a plain absolute http(s) url), template_needs_mail_channel (given with push or sms), template_not_configured (no template under that number), template_not_in_store (no mail template under that file id), template_url_too_long

Response Types

Type Version Description
MessageSeriesResult 1 Result of queueing or cancelling a message series

OpenAPI

See series.yaml

Referenced in skills