{"result":{"depiction_url":null,"edges":{"in_module":{"objects":[{"created":"2026-09-29T13:07:54Z","object_id":{"id":1465,"is_a":["text","documentation","reference","module"],"name":"doc_module_mod_mailinglist","title":"mod_mailinglist","uri":"https:\/\/zotonic.com\/id\/1465"},"seq":1}],"predicate":{"id":333,"is_a":["meta","predicate"],"name":"in_module","title":{"_type":"trans","tr":{"en":"In module"}},"uri":"https:\/\/zotonic.com\/id\/in_module"}},"subject":{"objects":[{"created":"2026-09-29T13:07:54Z","object_id":{"id":2555,"is_a":["categorization","keyword","keyword_information_type"],"name":"zotonic_topic_reference","title":"Reference","uri":"https:\/\/zotonic.com\/id\/2555"},"seq":1},{"created":"2026-09-29T13:07:54Z","object_id":{"id":2564,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_backend_developer","title":"Backend developer","uri":"https:\/\/zotonic.com\/id\/2564"},"seq":2},{"created":"2026-09-29T13:07:54Z","object_id":{"id":2597,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_mailing_lists","title":"Mailing lists","uri":"https:\/\/zotonic.com\/id\/2597"},"seq":3},{"created":"2026-09-29T13:07:54Z","object_id":{"id":2625,"is_a":["categorization","keyword","keyword_architecture"],"name":"zotonic_topic_model","title":"Model","uri":"https:\/\/zotonic.com\/id\/2625"},"seq":4},{"created":"2026-09-29T13:07:54Z","object_id":{"id":2654,"is_a":["categorization","keyword","keyword_task"],"name":"zotonic_topic_send_and_receive","title":"Send and receive","uri":"https:\/\/zotonic.com\/id\/2654"},"seq":5},{"created":"2026-09-29T13:07:54Z","object_id":{"id":2656,"is_a":["categorization","keyword","keyword_task"],"name":"zotonic_topic_schedule","title":"Schedule","uri":"https:\/\/zotonic.com\/id\/2656"},"seq":6},{"created":"2026-09-29T13:07:54Z","object_id":{"id":2657,"is_a":["categorization","keyword","keyword_task"],"name":"zotonic_topic_monitor","title":"Monitor","uri":"https:\/\/zotonic.com\/id\/2657"},"seq":7}],"predicate":{"id":308,"is_a":["meta","predicate"],"name":"subject","title":{"_type":"trans","tr":{"en":"Keyword"}},"uri":"http:\/\/purl.org\/dc\/elements\/1.1\/subject"}}},"id":2711,"is_a":["text","documentation","reference","model"],"links":[{"rel":"self","target":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/2711"},{"rel":"hub","target":"https:\/\/zotonic.com\/.zotonic\/websub"}],"medium":null,"medium_url":null,"name":"doc_model_model_mailinglist_run","page_url":{"en":"https:\/\/zotonic.com\/docs\/2711\/mailinglist_run","x-default":"https:\/\/zotonic.com\/docs\/2711\/mailinglist_run"},"preview_url":null,"resource":{"version":19,"pivot_location_lat":null,"title":"mailinglist_run","is_authoritative":true,"body":"

Durable mailing runs and delivery accounting, available as m.mailinglist_run<\/code> in templates.\nRecipient addresses and message diagnostics are never published on MQTT.\nInternal worker functions require an already authorized sender context.<\/p>\n

Available Model API Paths<\/h2>\n
Method<\/th>Path pattern<\/th>Description<\/th><\/tr><\/thead>
get<\/code><\/td>\/<\/code><\/td>List accessible runs, optionally filtered by a payload map.<\/td><\/tr>
get<\/code><\/td>\/history\/...<\/code><\/td>Return accessible runs and a next-page offset, using the same payload filters as the root path.<\/td><\/tr>
get<\/code><\/td>\/run\/+run_id\/...<\/code><\/td>Return a run with aggregate statistics, language results and saved-content metadata.<\/td><\/tr>
get<\/code><\/td>\/recipients\/+run_id\/...<\/code><\/td>Return up to 100 recipient results, optionally filtered and paged using the payload.<\/td><\/tr>
get<\/code><\/td>\/page\/+page_id\/...<\/code><\/td>List accessible runs for a page. Resource names and ids are accepted.<\/td><\/tr>
get<\/code><\/td>\/list\/+list_id\/...<\/code><\/td>List accessible runs for a mailinglist. Resource names and ids are accepted.<\/td><\/tr>
get<\/code><\/td>\/history_expired\/+page_id\/+list_id\/...<\/code><\/td>Return whether any run for this page\/list pair has expired recipient details. Both ids must be numeric.<\/td><\/tr>
get<\/code><\/td>\/recent\/...<\/code><\/td>Return up to five accessible recent runs, newest first, from the latest 200 runs.<\/td><\/tr><\/tbody><\/table>\n

\/+name<\/code> marks a variable path segment. A trailing \/...<\/code> means extra path segments\nare returned for further lookups. Run ids accept integers or numeric binaries.\nUnrecognized paths return {error, unknown_path}<\/code>.<\/p>\n

Run lists and filters<\/h2>\n

List results contain run metadata, including ids, language settings, status, timestamps,\ntest\/resend information, errors and details_expired<\/code>, plus a stats<\/code> map.\nExcept for \/recent<\/code>, runs in preparing<\/code>, sending<\/code>, retrying<\/code> or interrupted<\/code> status\ncome first; within each group the newest creation time and id come first.\nEach query selects at most 200 rows before checking access, so fewer rows may be returned.<\/p>\n

The root path accepts a payload map with binary keys:<\/p>\n
Key<\/th>Default<\/th>Meaning<\/th><\/tr><\/thead>
status<\/code><\/td>Empty binary<\/td>Exact run status; empty means all statuses.<\/td><\/tr>
language<\/code><\/td>Empty binary<\/td>Exact run language setting; empty means all languages.<\/td><\/tr>
page_id<\/code><\/td>0<\/code><\/td>Numeric page id; zero means all pages.<\/td><\/tr>
list_id<\/code><\/td>0<\/code><\/td>Numeric mailinglist id; zero means all lists.<\/td><\/tr>
offset<\/code><\/td>0<\/code><\/td>Rows to skip before access checks, capped at 1,000,000.<\/td><\/tr><\/tbody><\/table>\n

For example, m.mailinglist_run::%{status: "scheduled", list_id: id}<\/code> lists scheduled\nruns for a mailinglist. m.mailinglist_run.page[id]<\/code> lists runs for a page.\nFilters apply to the root and \/history<\/code> paths; \/page<\/code>, \/list<\/code> and \/recent<\/code> ignore the payload.\n\/history<\/code> returns a map with runs<\/code> and next_offset<\/code>. Use next_offset<\/code> as the next\nrequest's offset<\/code>; undefined<\/code> means there is no next page (or the offset cap was reached).\nPagination is based on database rows, independently of access filtering. A page may\ncontain fewer than 200 visible runs, or none, while still providing a next-page offset.<\/p>\n

Run details and statistics<\/h2>\n

m.mailinglist_run.run[run_id]<\/code> returns the run without its internal pickled_context<\/code>,\noptions<\/code>, props<\/code> or request_key<\/code>. It adds:<\/p>\n

  • stats<\/code>: recipient counts per status, plus total<\/code>, selected<\/code>, waiting<\/code>,\nunsuccessful<\/code>, processed<\/code> and integer percent<\/code>.<\/li>
  • languages<\/code>: nonzero counts as maps containing language<\/code>, status<\/code> and total<\/code>,\nordered by language and status.<\/li>
  • copies<\/code>: saved-content metadata containing language<\/code> and created<\/code>, ordered by language.<\/li>
  • first_submitted<\/code>: the first email submission timestamp, if available.<\/li>
  • test_address<\/code>: the single test recipient address, if this run has one.<\/li>
  • language_policy<\/code>: all<\/code> to use the fallback for unavailable preferences, or\nmatching<\/code> to skip unavailable or unset preferences when choosing languages\nautomatically. Absent on older runs, which keep their original behavior.<\/li><\/ul>\n

    selected<\/code> excludes skipped recipients; waiting<\/code> sums pending, submitting, queued and\nretrying recipients. unsuccessful<\/code> sums failed and bounced recipients. processed<\/code> is\nselected minus waiting; percent<\/code> is the integer percentage processed, or zero if none\nwere selected. Individual status keys with no recorded count may be absent.\nSent counts mean acceptance by the receiving mail server, not confirmed inbox delivery.\nSaved HTML is read through content\/3<\/code> and the saved-content controller, not an m_get<\/code> path.<\/p>\n

    Recipient results<\/h2>\n

    The \/recipients\/+run_id<\/code> payload accepts status<\/code> and after<\/code> with binary keys.\nstatus<\/code> can be pending<\/code>, submitting<\/code>, queued<\/code>, retrying<\/code>, sent<\/code>, failed<\/code>,\nbounced<\/code>, skipped<\/code> or cancelled<\/code>. An omitted, empty or unrecognized status means all.\nafter<\/code> is a recipient-row id, defaulting to zero. Results are ordered by id ascending;\nuse the last returned id as after<\/code> to fetch the next batch of up to 100 rows.<\/p>\n

    Each result contains id<\/code>, email<\/code>, language<\/code>, status<\/code>, reason<\/code> and modified<\/code>.\nFor example: m.mailinglist_run.recipients[run_id]::%{status: "failed", after: last_id}<\/code>.\nExpired recipient details return an empty list; aggregate statistics remain available.<\/p>\n

    Access and expired history<\/h2>\n

    Run reads require permission to use mod_mailinglist<\/code>, visibility of the mailed page,\nand permission to edit the mailinglist. An authenticated sender may also read their own\ntest-list runs without edit permission on the test list. List paths omit inaccessible\nruns; \/run<\/code> and \/recipients<\/code> return {error, eacces}<\/code> for missing or inaccessible runs.<\/p>\n

    \/history_expired\/+page_id\/+list_id<\/code> instead checks\nmod_mailinglist:is_allowed_to_send(ListId, PageId, Context)<\/code> and returns\n{error, eacces}<\/code> if sending is not allowed. A true result means that recipient history\nfor this pair is incomplete, so a new mailing cannot reliably select only new or failed\nrecipients. It does not mean that every run for the pair has expired.<\/p>\n

    Successful m_get\/3<\/code> calls return {ok, {Value, Rest}}<\/code>; templates receive Value<\/code>\nand use any remaining path segments for further lookups.<\/p>","slug":"mailinglist_run","is_protected":false,"visible_for":0,"tz":"UTC","language":["en"],"doc_source_hash":"321ceed5d7125a181662e573acf52bd77b91803930023c52af66a8ef5ffccccd","is_featured":false,"content_group_id":{"id":2551,"is_a":["meta","content_group"],"name":"content_group_imported_docs","title":"Imported documentation","uri":"https:\/\/zotonic.com\/id\/content_group_imported_docs"},"category_id":{"id":322,"is_a":["meta","category"],"name":"model","title":"Models","uri":"https:\/\/test.zotonic.com\/id\/322"},"doc_source_path":"apps\/zotonic_mod_mailinglist\/src\/models\/m_mailinglist_run.erl","publication_start":"2026-09-29T13:07:54Z","github_url":"https:\/\/github.com\/zotonic\/zotonic\/blob\/master\/apps\/zotonic_mod_mailinglist\/src\/models\/m_mailinglist_run.erl","pivot_location_lng":null,"doc_source_kind":"model","name":"doc_model_model_mailinglist_run","is_unfindable":false,"is_published":true,"pivot_geocode":null,"created":"2026-09-29T13:07:54Z","uri":null,"doc_status":"current","is_dependent":false,"erlang_app":"zotonic_mod_mailinglist","publication_end":"9999-06-01T00:00:00Z","modifier_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"privacy":0,"doc_source_commit":"85498256abd162b9bc082d43a90c995844fd4408\n","erlang_module":"m_mailinglist_run","creator_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"modified":"2026-09-29T14:40:25Z","title_slug":"mailinglist_run"},"uri":"https:\/\/zotonic.com\/id\/2711","uri_template":"https:\/\/zotonic.com\/id\/:id","websub":{"hub":"https:\/\/zotonic.com\/.zotonic\/websub","topic":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/2711"}},"status":"ok"}