{mailbulk:list_or_info:item_or_list:item:what}

Description

Sends one item of a slice by e-mail to the readers of a mailing list, in the background, and shows how far the sending got. A list is a collection of an Alerts module (a five-character id such as 8g0lk); it holds the slice of readers, their confirmation and unsubscription. The sending runs in short steps of the task queue, so a click returns within seconds whether the list has a hundred readers or a hundred thousand, and no reader of the list gets the same item twice - not after a second click, a reload or a crashed step (such a step leaves one reader counted as uncertain rather than mailed twice). Since November 2026; installations not yet updated do not have the command.

Two forms. {mailbulk:LIST:ITEM} prints the control of the sending: one line with its state and buttons. {mailbulk:info:LIST:ITEM:WHAT} prints one value of the sending for a listing of your own: state (empty = never sent, sending, stopped, error, done), total, sent, failed, skipped, uncertain or date - see the parameter what. The figures are summed over all runs of the same item and list. Opens and clicks are not among the values; they are shown by the Statistics button and on the Alerts page (see Measuring below).

Who sees it: only a logged-in user with the right to edit all items of the item's slice, and only when the list belongs to that slice - the list's slice of readers is the item's slice, a filter of the list uses a view of the slice, or the site that uses the item's slice also uses the list's Alerts module or its slice of readers. Otherwise both forms print nothing (the control still appears, with only its Stop button, while a sending started before is running). The same holds for an invalid list or item id. A page with the command is never stored in the page cache.

Where it goes: the control is meant for a row of the admin item listing of the newsletter slice (for example a listing called Správa zpráv): {mailbulk:8g0lk:{_#ITEM_ID_}} - the item id alias in braces. Its buttons post to central/responder.php (POST only; expanding the template never sends anything), and AA refuses a request the browser marks as coming from another site - on a site of another domain than AA the buttons do not work.

The buttons: Test and Send... before the first sending; Stop while sending (the progress refreshes by itself); Continue... after a stop; Continue and Stop after an error (Continue goes on with the same run); Send to new... when done - it sends only to readers of the selection who have not got the item yet. Send..., Continue... and Send to new... first ask the server for the number of recipients and show the question "Send to N recipients?". Test sends at once, without a background run: the mail made for one reader (the reader with the test address, else the first one of the selection) goes to the test addresses; its unsubscribe and preferences links carry the dummy code ABCDE, which unsubscribes nobody, and it has no unsubscribe headers.

Statistics: once the item has been sent to the list at least once (any run, in any state), the control also has the button Statistics. A click shows the statistics block of the sending below the control, a second click hides it. The block holds the table of the runs (started, finished, state, recipients, sent, failed, skipped, uncertain; with more runs a Total row counting each reader once) and, when the list has a statistics slice, the number of readers who opened and who clicked and a table of the clicked links with the number of readers per link. The block is read only on the click, so a listing of many items computes no statistics.

What is sent comes from aliases of the item's slice (alias functions of any of its fields, typically f_t with the template as its parameter). Required: _#MAILSUBJ the subject, _#MAILBODY the HTML body, _#MAILFROM the sender (Name <address> or a bare address; it is also used for Reply-To, Errors-To and the envelope sender). Optional: _#MAILTO__ selects the readers - conditions written as the second parameter of the ids command (d-field-operator-value...); without it the mail goes to all valid readers of the list (active, with a confirmed address and an e-mail, not unsubscribed from this list); readers sharing one address get one mail. _#MAILTEST lists test addresses separated by commas (at most 10 are used); without it the test goes to the e-mail of the logged-in user. When something is missing or wrong - a required alias, a valid sender, an active item, a slice of readers - the control says so in place of the buttons.

A condition in _#MAILTO__ that the reader search would drop - a field the slice of readers does not have, an empty value, a value it cannot parse - stops the sending with that message rather than mailing everyone. The parts of a condition are separated by a dash, so a value spliced in from an item field that contains a dash splits the condition: build such a condition with the conds command in mode 1, which doubles every dash and quotes the value, e.g. d-category........-=-{conds:category.......1:1}.

Per reader: each mail is expanded for its reader, from the item as it is at that moment (a correction during the sending reaches the readers still waiting), in the language of the Alerts module, with four aliases added - _#MAILTOID the long id of the reader's item in the slice of readers (read the reader by {item:{_#MAILTOID}:_#FIRSTNAM}), _#MAILUNSB the reader's unsubscribe URL (see The unsubscribe link below), _#MAILPREF the URL of the reader's form (as _#COLLFORM), and _#MAILOPEN the image that counts the opening of the mail (empty when the sending measures nothing, see below). In a command parameter always write {_#MAILTOID} in braces: a bare alias reaches the command as the text _#MAILTOID, not as the reader's id, and is replaced only in the output - the name would stay empty for every reader. Outside a sending these four aliases are not defined and stay as text.

The unsubscribe link (since November 2026): _#MAILUNSB is the list's page with ?au=code&c=list&one=b. Mail scanners open the links of a mail, so on a page with the alerts command opening the link does not unsubscribe: the page shows the button Unsubscribe, and the click on it (a POST) unsubscribes. On a fillform (SSI) page, which a POST cannot reach, opening the link still unsubscribes. A test mail carries the plain link with the code ABCDE. Installations not yet updated put there the same link as _#UNSBFORM in Alerts digests, which unsubscribes on opening (it still does in the digests).

Measuring opens and clicks (since November 2026): only when the Alerts list has a statistics slice - the field Statistics slice in the settings of the Alerts module; empty means nothing is measured. Whether a sending measures is decided when it is sent, so adding or removing the slice later changes no mail of that run. In a measured sending every http and https link of the mail (the href of an a tag) is rewritten to a tracked address on the list's site, api/index.php?_path=v1/mail/hit&t=... under the path of AA, which records the click and redirects to the original address. Links stay as they are when they are the reader's unsubscribe or preferences link (_#MAILUNSB, _#MAILPREF) or carry the reader's id or access code - such an address must not end up in statistics that editors read. A 1x1 image that counts the opening goes where the body has _#MAILOPEN, else at the end of the body. Put _#MAILOPEN near the top of _#MAILBODY: Gmail clips a long mail, and an image at its end is then never loaded. A test mail is never measured.

Each reader is counted once: opened = readers with an opening, clicked = readers with at least one click; a click counts as an opening too (images may be blocked). No IP address is stored. The numbers are rough: some mail programs and services load the images by themselves, and mail scanners follow links. The same figures are on the page Mailings and statistics of the Alerts module: every sending of the list with its date, name, state and figures; a click opens one sending - its runs, its links and (since November 2026) the table of its recipients: e-mail, result, time sent, first opening and the clicked links with their times. The time sent comes from the AA log, which keeps 40 days; for an older mail the page shows ≈ the start of the run. Filters (all, opened, not opened, clicked, failed or uncertain) narrow the table, and it can be exported as CSV. The page is for the administrator of the Alerts module and for a user with the role Editor of the module, who sees only that page of the module.

Unsubscribe headers (List-Unsubscribe and List-Unsubscribe-Post for one-click unsubscription) are added to every mail of the sending, but only when the list's page is an https address - mail services post only to https. The header URL carries one=1 instead of one=b: opening it never unsubscribes (a page with the alerts command shows the button, a fillform page nothing); the one-click POST of the mail service (List-Unsubscribe=One-Click) unsubscribes on a page with the alerts command - a fillform page never gets the POST, so there the header unsubscribes nobody. See the alerts command.

Parameters

list_or_info required default (empty)

The id of the list - the five-character id of a collection of an Alerts module, e.g. 8g0lk - for the control. Or the word info for the second form, which prints one value of the sending instead of the control. An unknown or invalid list id prints nothing.

item_or_list required default (empty)

In the control form: the long id of the item to send; in a row of an item listing write {_#ITEM_ID_} (in braces). In the info form: the id of the list.

item optional default (empty)

Info form only: the long id of the item whose sending you ask about. Required in the info form, unused by the control.

what optional default (empty)

Info form only: which value of the sending to print. The figures count each reader once over all runs of the item and list. Opens and clicks are not here; any other name prints nothing. Without the right to edit all items of the item's slice, or for a list that does not belong to that slice, every value is empty.

Allowed values state (empty = never sent, sending, stopped, error, done - the state of the newest run), total (readers covered over all runs), sent, failed (refused by the address or the mail server), skipped (no longer a valid reader at their turn, or the mail came out empty), uncertain (a step stopped in the middle of the send; never sent again), date (Unix time when the last run that got done finished; empty before)

Examples

test[{mailbulk:8g0lk:{_#ITEM_ID_}}]
Expected[]
Actual[]
The form written into a row of the admin item listing of the newsletter slice; the alias in braces gives each row its own item. Here the row is this example, and the list 8g0lk does not belong to the slice of the examples, so the command prints nothing - for every visitor, logged in or not. In a row of the newsletter slice an editor of that slice gets the control.
virtual{safe:{mailbulk:8g0lk:853e53553f0d3692e464ca9f17148393}}
Expected(for an editor of the newsletter slice: <span class="aa-mailbulk" data-aa-mailbulk data-list="8g0lk" data-item="853e53553f0d3692e464ca9f17148393" data-state="done"><span class="aa-mailbulk-text">2026-11-14 11:39</span> <span class="aa-mailbulk-text">sent 3</span> <button type="button" data-action="send">Send to new...</button> <button type="button" data-action="stats">Statistics</button></span> - empty for anyone else)
The test newsletter item, sent to the test list: the date of the end, the nonzero figures, the button Send to new... (it asks for the number of new readers first) and the button Statistics, which shows the statistics block of the sending below the control and hides it again (since November 2026; it appears once the item has a run). Wrapped in safe here so that the docs page shows the markup, not a working button. What it prints depends on the viewer, so this is not a test: a visitor without the right - the test runner too - gets an empty string.
virtual{mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:state}
Expected(done for an editor of the newsletter slice; empty for anyone else)
Empty means never sent; otherwise sending, stopped, error or done. It depends on the rights of the viewer, so it is not a test.
virtualstate={mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:state} total={mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:total} sent={mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:sent} failed={mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:failed} skipped={mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:skipped} uncertain={mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:uncertain} date={mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:date}
Expected(state=done total=3 sent=3 failed=0 skipped=0 uncertain=0 date=1794652790 for an editor; every value empty for anyone else)
Actualstate= total= sent= failed= skipped= uncertain= date=
The figures count each reader once over all runs of the item and the list; date is a Unix time. Not a test - the values need the right to edit all items of the newsletter slice.
virtual{ifset:{mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:date}:{date:Y-m-d H#:i:{mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:date}}}
Expected(2026-11-14 11:39 for an editor; empty for anyone else)
Guard the date by ifset: date is empty until a run is done, and the date command with an empty time prints the current date. The colon of the time format is escaped as #:.
test[{ifeq:{mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:state}:sending:still being sent:not being sent}]
Expected[not being sent]
Actual[not being sent]
A branch on the state, for a listing of your own. The item is done for an editor and empty for anyone else - neither is sending - so every viewer gets the same result and it can serve as a test.
test[{mailbulk:info:8g0lk:853e53553f0d3692e464ca9f17148393:opens}]
Expected[]
Actual[]
Only state, total, sent, failed, skipped, uncertain and date exist; any other name - opens and clicks too - prints nothing, for everyone.
test[{mailbulk:zzzzz:853e53553f0d3692e464ca9f17148393}]
Expected[]
Actual[]
A list id that does not exist prints nothing, even for a superadmin.
test{item:853e53553f0d3692e464ca9f17148393:_#MAILSUBJ}
ExpectedMailbulk test newsletter 1
ActualMailbulk test newsletter 1
_#MAILSUBJ, _#MAILBODY and _#MAILFROM are ordinary aliases of the newsletter slice, so any template can show them for an item - here _#MAILSUBJ is defined as the headline. Unlike the control, this needs no special right.
test{safe:{item:853e53553f0d3692e464ca9f17148393:_#MAILBODY}}
Expected<p>Hello [],</p>This is the body of the test newsletter.<p><a href="_#MAILUNSB">Unsubscribe</a> | <a href="_#MAILPREF">Preferences</a></p>
Actual<p>Hello [],</p>This is the body of the test newsletter.<p><a href="_#MAILUNSB">Unsubscribe</a> | <a href="_#MAILPREF">Preferences</a></p>
The body of the test newsletter as a page shows it. The name and the unsubscribe and preferences links are filled in only in the mail of each reader: outside a sending _#MAILTOID is not defined, so the name is empty, and _#MAILUNSB and _#MAILPREF stay as text.
virtual_#MAILOPEN<p>Hello {item:{_#MAILTOID}:_#FIRSTNAM},</p><p>The text of the newsletter.</p><p><a href="https://example.org/article">Read more</a></p><p><a href="_#MAILUNSB">Unsubscribe</a></p>
Expected(in the mail of each reader: the 1x1 image counting the opening when the list measures, Hello and the first name of that reader, the text, the Read more link - tracked when the list measures - and the unsubscribe link of that reader)
Actual_#MAILOPEN

Hello ,

The text of the newsletter.

Read more

Unsubscribe

A _#MAILBODY template, written as the parameter of the f_t alias function of a field of the newsletter slice. _#FIRSTNAM is an alias of the slice of readers; the item command reads it from the reader's own item. Keep _#MAILTOID in braces inside the parameter: bare, the item command would get the text _#MAILTOID instead of the reader's id, and the name would stay empty in every mail. _#MAILOPEN at the top places the image that counts the opening when the list has a statistics slice (since November 2026); without it the image goes to the end of the body, which Gmail cuts off in a long mail. In such a sending the Read more link becomes a tracked address; the unsubscribe link stays as it is.
testd-category........-=-{conds:["news-2026"]:1}
Expectedd-category........-=-"news--2026"
Actuald-category........-=-"news--2026"
_#MAILTO__ holds conditions written as the second parameter of ids. Their parts are split at dashes, so a value with a dash - here news-2026 - would cut the condition, and a condition the reader search cannot use stops the sending. The conds command in mode 1 doubles the dash and quotes the value. In the alias give it the field id of the newsletter item instead of the list, e.g. category.......1 with mode 1.