← 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