MailerSendEmail

POST mailer/email

Queues one email. The method answers as soon as the message is accepted into the queue: attempts, backoff and failover to a backup profile happen afterwards, without the caller waiting for the provider.

Content comes either from a template (templateId) or from the request (subject plus html/text/structure). Whatever the source, the module assembles the final message: placeholders are substituted with HTML escaping, a plain-text part is generated when missing, and a MARKETING email gets its unsubscribe link and List-Unsubscribe headers.

Access Control

Allowed roles: admin, leader, manager. The email is created under the brand of the caller, and the author comes from the session.

Request

RESTTCPSDK

POST https://{broker_domain}/mailer/email

{
  "sendToParentType": "CUSTOMER",
  "sendToParentId": 140,
  "to": "[email protected]",
  "templateId": 4,
  "data": {
    "name": "John",
    "amount": "250 EUR"
  },
  "kind": "TRANSACTIONAL",
  "idempotencyKey": "deposit-140-1755000000"
}

{
  "command": "MailerSendEmail",
  "extID": "1",
  "data": {
    "sendToParentType": "CUSTOMER",
    "sendToParentId": 140,
    "to": "[email protected]",
    "templateId": 4,
    "data": {
      "name": "John",
      "amount": "250 EUR"
    },
    "kind": "TRANSACTIONAL",
    "idempotencyKey": "deposit-140-1755000000"
  }
}

const res = await platform.MailerSendEmail({
  sendToParentType: "CUSTOMER",
  sendToParentId: 140,
  to: "[email protected]",
  templateId: 4,
  data: {
    name: "John",
    amount: "250 EUR"
  },
  kind: "TRANSACTIONAL",
  idempotencyKey: "deposit-140-1755000000"
});

Request Data

Field	Type	Required	Description
sendToParentType	enum	Yes	CUSTOMER, MANAGER, or LEAD — what the address belongs to
sendToParentId	int	Yes	Id of the customer, lead, or manager
to	string	Yes	Recipient address
templateId	int	No	Template to render; use it instead of passing content
subject	string	No	Subject, up to 512 characters
html	string	No	HTML body
text	string	No	Plain-text part; generated from the HTML when omitted
structure	array	No	Email builder tree; the HTML is rendered from it
data	object	No	Placeholder values
cc	array	No	Copy recipients
bcc	array	No	Blind copy recipients
replyToEmail	string	No	Reply-To address; falls back to the profile default
attachments	array	No	Attachments: { filename, contentType?, size?, url?, content? }. url is fetched at send time, content is base64 for small files
profileId	int	No	Explicit provider profile. Omit to let routing choose
agentId	int	No	Explicit agent link for INDIVIDUAL profiles
kind	enum	No	TRANSACTIONAL ignores send windows and marketing unsubscribes; MARKETING is the default
sendAt	string	No	Defer sending: ISO 8601 or YYYY-MM-DD HH:mm:ss
idempotencyKey	string	No	Repeating a request with the same key returns the same email instead of sending a second one
countryIso	string	No	Recipient country for send windows; taken from the CRM card when omitted

Behavior

• Checks that can reject the email for free run before the provider is contacted: address validity, suppression list, duplicate window, assembled size, attachment limits, recipient domain, send window.
• A MARKETING email always leaves with an unsubscribe link and List-Unsubscribe plus List-Unsubscribe-Post headers — without them Gmail and Outlook treat the sender as a spammer regardless of content.
• Attachments passed by url are fetched when the email is sent, not when it is queued: a ten-megabyte file in the queue row would be re-read on every attempt and returned in every list response.
• scheduleReason explains why an email is still waiting: IMMEDIATE, SEND_WINDOW, or SCHEDULED.

Response Data

{
  "emailId": 812,
  "status": "PENDING",
  "to": "[email protected]",
  "subject": "John, your deposit of 250 EUR is confirmed",
  "kind": "TRANSACTIONAL",
  "profileId": 3,
  "scheduledFor": null,
  "scheduleReason": "IMMEDIATE",
  "idempotent": false
}

Errors

Code	Error	Description
400	INVALID_EMAIL_ADDRESS	Address cannot be parsed, or its domain looks like a typo
400	VALIDATION_ERROR	Neither content nor template was provided, or a field is out of range
400	INVALID_SEND_AT	sendAt is unparsable, in the past, or beyond the allowed horizon
403	EMAIL_SUPPRESSED	Address is on the suppression list: hard bounce, complaint, block or manual entry
403	RECIPIENT_UNSUBSCRIBED	Recipient unsubscribed; only MARKETING is blocked
404	NOT_FOUND	Profile, provider, template, or agent not found
409	MESSAGE_TOO_LARGE	Assembled message exceeds the configured size limit
409	DUPLICATE_EMAIL	The same subject to the same address inside the duplicate window
409	DOMAIN_NOT_ALLOWED	Recipient domain is not allowed for the profile
409	NO_ROUTE_AVAILABLE	No profile of the brand can send to this recipient
409	ATTACHMENT_NOT_ALLOWED	Attachment type is not in the allow list, or the count or total size limit is exceeded
500	MISSING_CREDENTIALS	Profile credentials are incomplete for this adapter