Mailer REST API

The REST transport addresses a module method by HTTP method and path. It is the entry point for the CRM interface, the backoffice, mobile applications, provider event callbacks and unsubscribe links.

The same methods are available over TCP by command name — see TCP API. Request fields and results are identical; only the addressing differs.

Base URL

https://{broker_domain}/mailer/...

All paths of the module live under mailer/. The prefix is what keeps the module apart from the other modules sharing the same host — including the two public paths, the provider webhook and the unsubscribe endpoint.

Authorization

Every endpoint except the two public ones requires a manager JWT:

Authorization: <JWT_TOKEN>

The platform resolves the token and passes the identity to the module. The brand and the author of a record always come from the token, never from the request body.

Two endpoints are public by necessity:

Endpoint	Why it is public	What protects it
POST mailer/handleWebhooks/:uuid	called by the email provider	unguessable uuid plus a signature check against the webhook secret
POST mailer/unsubscribe	called by the recipient or their mail client	HMAC-signed token carrying the address, brand and expiry

Endpoints

Method	Endpoint	Access
MailerSendEmail	POST mailer/email	admin, leader, manager
MailerSendBulk	POST mailer/email/bulk	admin, leader
MailerResendEmail	POST mailer/email/resend	admin, leader, manager
MailerCancelEmail	POST mailer/email/cancel	admin, leader, manager
MailerPreviewEmail	POST mailer/email/preview	admin, leader, manager
MailerLintEmail	POST mailer/email/lint	admin, leader
MailerSendTestEmail	POST mailer/email/test	admin, leader
MailerFindEmail	GET mailer/email/find	admin, leader
MailerGetEmail	GET mailer/email/message/:id	admin, leader, manager
MailerGetEmails	GET mailer/emails/list	admin, leader, manager
MailerGetStats	GET mailer/email/stats	admin, leader
MailerAddCampaign	POST mailer/campaign	admin, leader
MailerUpdateCampaign	PUT mailer/campaign	admin, leader
MailerCancelCampaign	POST mailer/campaign/cancel	admin, leader
MailerResumeCampaign	POST mailer/campaign/resume	admin, leader
MailerEstimateCampaignRecipients	POST mailer/campaign/estimate-recipients	admin, leader
MailerDeleteCampaign	DELETE mailer/campaign	admin, leader
MailerGetCampaigns	GET mailer/campaigns/list	admin, leader
MailerAddTemplate	POST mailer/template	admin
MailerUpdateTemplate	PUT mailer/template	admin
MailerCloneTemplate	POST mailer/template/clone	admin
MailerDeleteTemplate	DELETE mailer/template	admin
MailerGetTemplates	GET mailer/templates/list	admin, leader, manager
MailerAddTrigger	POST mailer/trigger	admin
MailerUpdateTrigger	PUT mailer/trigger	admin
MailerDeleteTrigger	DELETE mailer/trigger	admin
MailerFireTrigger	POST mailer/trigger/fire	admin
MailerGetTriggers	GET mailer/triggers/list	admin
MailerGetTriggerSubscriptions	GET mailer/triggers/subscriptions	admin
MailerGetProviderAdapters	GET mailer/providers/adapters	admin, provider
MailerAddProvider	POST mailer/provider	provider
MailerUpdateProvider	PUT mailer/provider	provider
MailerDeleteProvider	DELETE mailer/provider	provider
MailerGetProviders	GET mailer/providers/list	admin, provider
MailerAddProfile	POST mailer/providerProfile	admin
MailerUpdateProfile	PUT mailer/providerProfile	admin
MailerDeleteProfile	DELETE mailer/providerProfile	admin
MailerGetProfiles	GET mailer/providerProfiles/list	admin
MailerGetMyProfiles	GET mailer/providerProfile/available/me	admin, leader, manager
MailerGetProfileBalance	GET mailer/providerProfiles/balance	admin
MailerVerifyProfileDomain	POST mailer/providerProfile/verify-domain	admin
MailerAddAgent	POST mailer/agent	admin
MailerUpdateAgent	PUT mailer/agent	admin
MailerDeleteAgent	DELETE mailer/agent	admin
MailerGetAgents	GET mailer/agents/list	admin
MailerAddSuppression	POST mailer/suppression	admin, leader
MailerImportSuppressions	POST mailer/suppression/import	admin
MailerDeleteSuppression	DELETE mailer/suppression	admin
MailerCheckSuppression	GET mailer/suppression/check	admin, leader, manager
MailerGetSuppressions	GET mailer/suppressions/list	admin, leader
MailerHandleUnsubscribe	POST mailer/unsubscribe	public
MailerAddSendWindow	POST mailer/sendWindow	admin
MailerUpdateSendWindow	PUT mailer/sendWindow	admin
MailerDeleteSendWindow	DELETE mailer/sendWindow	admin
MailerCheckSendWindow	GET mailer/sendWindow/check	admin, leader, manager
MailerGetSendWindows	GET mailer/sendWindows/list	admin, leader
MailerAddWebhook	POST mailer/webhook	admin
MailerUpdateWebhook	PUT mailer/webhook	admin
MailerDeleteWebhook	DELETE mailer/webhook	admin
MailerGetWebhooks	GET mailer/webhooks/list	admin
MailerGetWebhookEvents	GET mailer/webhookEvents/list	admin
MailerHandleWebhook	POST mailer/handleWebhooks/:uuid	public
MailerPing	GET mailer/ping	admin
MailerHealth	GET mailer/health	admin

MailerGetLastEmailsByParents has no REST route: it is an internal method for CRM lists and is available over the bus only.

List queries

Every */list method accepts the same query contract:

Field	Type	Description
limit	int	Page size, 1..1000, default 100
offset	int	Rows to skip
orderBy	array	["id", "DESC"]
groupBy	array	Grouping, including date grouping such as DAY({field})
count, sum, min, max, avg	array	Aggregates over the listed fields
where, whereIn, whereLike, whereBetween, …	object	Filters, including grouped orWhere

Filter syntax is shared with the rest of the platform and is described in Table filter syntax.

The response is the requested page in rows, plus one key per requested aggregate:

{
  "rows": [],
  "count": [ { "id": 42 } ]
}

A row count is an aggregate, not a default: ask for it with count: ["id"] when the UI needs paging. For deliverability reports use MailerGetStats — it aggregates on the server instead of paging raw rows.

Status codes

Code	Meaning
200	Method succeeded
400	Validation failed, or the request contradicts itself
401	Missing or invalid JWT
403	The manager may not touch this record, or the address is suppressed
404	Email, profile, provider, template, campaign, or adapter not found
409	Sending is not allowed: unsubscribe, recipient domain, duplicate, size, attachments
422	Template content uses unsupported syntax
429	Provider rate limit
500	Module or storage error
502	Module is unreachable on the bus
503	Provider is unavailable

On success the body is the method payload itself — there is no wrapper object to unwrap:

{ "emailId": 812, "status": "PENDING", "scheduleReason": "IMMEDIATE" }

On failure the HTTP status carries the outcome and the body is the message:

HTTP/1.1 403 Forbidden

"Address [email protected] is suppressed: HARD_BOUNCE"

Branch on the status code and show the message to the operator. The error type listed on each method page names the same condition and appears in the module log; at the HTTP boundary the status code is the machine-readable part.