Mass Mailer API
The mass mailer sends one message to many clients: those who match its filter (client status, client groups, products ordered, order status). The content is Markdown with the client’s details as variables, such as {{ c.first_name }}. Clients who opted out of marketing email are skipped. See Mass mailer.
Admin calls need Module access on the Massmailer card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.
Admin calls
Section titled “Admin calls”get_list
Section titled “get_list”POST /api/admin/massmailer/get_list
Lists mass mail messages, newest first.
Permission: View mass mail messages (massmailer.view)
| Parameter | Type | Description |
|---|---|---|
search |
string | Matches the subject, content, sender email or sender name. |
status |
string | draft, scheduled, sending or sent. |
id |
integer | One message id. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row is a message as in get plus recipients (how many clients it was sent to; 0 before sending).
POST /api/admin/massmailer/get
Returns one message.
Permission: View mass mail messages (massmailer.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message id. |
Returns: id, from_email, from_name, subject, content (Markdown), filter (client_status, client_groups, has_order, has_order_with_status; empty ones left out), marketing, status (draft, scheduled, sending, sent), scheduled_at, sent_at, created_at, updated_at.
Errors:
- Message not found (code 9999)
Example
Request parameters:
{ "id": 4}result:
{ "id": 4, "from_email": "billing@example.com", "from_name": "Example Hosting", "subject": "Planned maintenance", "content": "Hello {{ c.first_name }},\n\nWe will upgrade our servers on Sunday.", "filter": { "client_status": [ "active" ], "has_order_with_status": [ "active" ] }, "status": "draft", "scheduled_at": null, "sent_at": null, "created_at": "2026-11-17 09:00:00", "updated_at": "2026-11-17 09:05:00"}update
Section titled “update”POST /api/admin/massmailer/update
Changes a draft or scheduled message. Only the fields you send change.
Permission: Create and edit mass mail messages (massmailer.create_and_edit)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message id. |
subject |
string | At most 255 characters; may use the client variables. |
content |
string | The message in Markdown; may use the client variables, such as {{ c.first_name }}. |
from_name |
string | Sender name, not empty, at most 255 characters. |
from_email |
string | Sender email, at most 255 characters. |
marketing |
boolean | A marketing message (on for a new message): clients who opted out of marketing email are skipped. Off for a service notice that reaches every client in the filter. |
filter |
object | Who gets it: client_status (active, inactive, suspended, canceled), client_groups (client group ids; a client in any of them), has_order (product ids) and has_order_with_status (pending_setup, failed_setup, failed_renew, active, canceled, suspended), each a list. An empty filter means every client. |
Returns: true.
Errors:
- Message not found (code 9999)
- This message was already sent. (code 9999) for a message that is sending or sent
- Use at most 255 characters. (code 9999)
- Message from name cannot be empty (code 9999)
- Mass mail filter contains invalid values for “client_groups” (code 9999)
create
Section titled “create”POST /api/admin/massmailer/create
Creates a draft message. The sender defaults to the company name and email.
Permission: Create and edit mass mail messages (massmailer.create_and_edit)
| Parameter | Type | Description |
|---|---|---|
subject |
string, required | At most 255 characters. |
content |
string | The message in Markdown. |
from_name |
string | Sender name. |
from_email |
string | Sender email. |
marketing |
boolean | A marketing message, as in update; on when left out. |
filter |
object | Who gets it, as in update. |
Returns: The new message id.
Errors:
- Use at most 255 characters. (code 9999)
- Mass mail filter contains invalid values for “has_order” (code 9999)
Example
Request parameters:
{ "subject": "Planned maintenance", "content": "Hello {{ c.first_name }},\n\nWe will upgrade our servers on Sunday.", "filter": { "client_status": [ "active" ] }}result:
4send_test
Section titled “send_test”POST /api/admin/massmailer/send_test
Sends the message at once to the test client set in the mass mailer settings.
Permission: Send mass mail (massmailer.send)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message id. |
Returns: true.
Errors:
- Message not found (code 9999)
- Add some content before sending message (code 9999)
- Client ID needs to be configured in mass mailer settings. (code 9999)
- The test client opted out of marketing email. (code 9999)
POST /api/admin/massmailer/send
Sends the message now to every client its filter matches: the emails go to the email queue.
Permission: Send mass mail (massmailer.send)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message id. |
Returns: true.
Errors:
- Message not found (code 9999)
- Add some content before sending message (code 9999)
- This message was already sent. (code 9999)
- Mass mail filter contains invalid values for “client_groups” (code 9999) when the filter no longer works, such as a deleted client group
A message is sent once: the recipients are fixed when sending starts, and cron finishes a send that was cut off without mailing anyone twice. Opted-out clients are skipped and get an unsubscribe link otherwise. This cannot be undone.
schedule
Section titled “schedule”POST /api/admin/massmailer/schedule
Schedules a draft (or already scheduled) message to be sent by cron at a later time.
Permission: Send mass mail (massmailer.send)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message id. |
scheduled_at |
string, required | A date and time in the future, such as 2026-11-20 09:00. |
Returns: true.
Errors:
- Add some content before sending message (code 9999)
- Pick a date and time in the future. (code 9999)
- This message was already sent. (code 9999)
If the filter no longer works when it is due, the message becomes a draft again.
cancel_schedule
Section titled “cancel_schedule”POST /api/admin/massmailer/cancel_schedule
Cancels a scheduled send: the message becomes a draft again.
Permission: Send mass mail (massmailer.send)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message id. |
Returns: true.
Errors:
- Message not found (code 9999)
- This message was already sent. (code 9999) when it is not scheduled
report
Section titled “report”POST /api/admin/massmailer/report
The delivery report of a sent message: each recipient and what happened to their email.
Permission: View mass mail messages (massmailer.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message id. |
Returns: counts (sent, queued, failed, skipped) and recipients, each {client_id, name, email, status} with one of those statuses (skipped: the client opted out).
Errors:
- Message not found (code 9999)
Example
Request parameters:
{ "id": 4}result:
{ "counts": { "sent": 1, "queued": 0, "failed": 0, "skipped": 1 }, "recipients": [ { "client_id": 8, "name": "John Smith", "email": "john@example.com", "status": "skipped" }, { "client_id": 7, "name": "Jane Doe", "email": "jane@example.com", "status": "sent" } ]}POST /api/admin/massmailer/copy
Makes a draft copy of a message with the same sender, content and filter, its subject ending in “(Copy)”.
Permission: Create and edit mass mail messages (massmailer.create_and_edit)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message to copy. |
Returns: The new message id.
Errors:
- Message not found (code 9999)
receivers
Section titled “receivers”POST /api/admin/massmailer/receivers
Lists the clients the message’s filter matches now.
Permission: View mass mail messages (massmailer.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message id. |
Returns: A list, newest client first, of {id, name, email, opted_out}; opted-out clients would be skipped.
Errors:
- Message not found (code 9999)
- Mass mail filter contains invalid values for “client_groups” (code 9999)
delete
Section titled “delete”POST /api/admin/massmailer/delete
Deletes a message and its delivery report.
Permission: Delete mass mail messages (massmailer.delete)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message id. |
Returns: true.
Errors:
- Message not found (code 9999)
- This message was already sent. (code 9999) while it is sending
Emails already in the email queue are not taken back.
preview
Section titled “preview”POST /api/admin/massmailer/preview
Renders the message’s subject and content as one client would get them.
Permission: View mass mail messages (massmailer.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The message id. |
client_id |
integer | The client to render it for. Default: the test client from the settings. |
Returns: {subject, content}; the content is HTML with the email signature.
Errors:
- Message not found (code 9999)
- Client ID needs to be configured in mass mailer settings. (code 9999)
get_test_client
Section titled “get_test_client”POST /api/admin/massmailer/get_test_client
The email of the test client set in the mass mailer settings.
Permission: View mass mail messages (massmailer.view)
No parameters.
Returns: The email, or "Unknown" when no test client is set or it does not exist.

