Skip to content

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.

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), 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"
}

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.
filter object Who gets it: client_status (active, 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)

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.
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:

4

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.

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.

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

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)

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)

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.

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)

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.