SendMailToGroupCommand

Category: Communication Commands
Permission: bnk_send_group_mail

Send an email to a group of back-office users resolved by role IDs, permission codes, or both — with an optional branch filter.

---

Overview

SendMailToGroupCommand resolves recipients dynamically at runtime from the user management database, then dispatches the email via SendMailCommand. It supports both the legacy RolePermission table and the newer DirectPermissions system, so all role setups are covered.

Recipient Resolution Order

1. If roleIds provided → include all users in those roles
2. If permissionCodes provided → resolve roles that carry any of those permissions, include their users
3. Union both sets (duplicates removed)
4. If branchIds provided → keep only users in those branches

At least one of roleIds or permissionCodes must be supplied.

---

When to Use

✅ Use For:	❌ Don't Use For:
Notifying approvers a task is pending	Real-time alerts (use SendNotificationToGroupCommand)
Bulk announcements to a department	Individual customer emails (use SendMailCommand)
Escalation emails to branch managers	SMS delivery (use SendSMSCommand)

---

Parameters

Recipient Selection (at least one required)

Parameter	Type	Description
permissionCodes	string[]	Users whose role includes ANY of these permission codes
roleIds	long[]	Users directly assigned to any of these role IDs

Optional Filters

Parameter	Type	Description
branchIds	long[]	When provided, restricts recipients to users in those branches

Email Content

Parameter	Type	Required	Description
subject	string	Yes	Email subject line
message	string	When no templateId	Plain/HTML message body
templateId	string	When no message	HtmlTemplateDefinition name to render
context	object	No	Template render context (used with templateId)
sender	string	No	Override the from address

Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Email sent to 5 recipient(s).",
  "data": {
    "recipientCount": 5,
    "recipients": ["alice@bank.com", "bob@bank.com"]
  }
}

---

Examples

By Permission Code (all branches)

doCmd('SendMailToGroupCommand', {
  Data: {
    permissionCodes: ['bnk_approve_loan'],
    subject: 'New Loan Pending Approval',
    message: '<p>A new loan application is awaiting your review.</p>'
  }
});

By Role ID

doCmd('SendMailToGroupCommand', {
  Data: {
    roleIds: [5, 7],
    subject: 'System Maintenance Tonight',
    message: '<p>Scheduled maintenance from 11pm–1am.</p>'
  }
});

Combined — Roles + Permissions + Branch Filter

doCmd('SendMailToGroupCommand', {
  Data: {
    permissionCodes: ['bnk_approve_loan'],
    roleIds: [12],
    branchIds: [3, 8],
    subject: 'Urgent: Pending Approval',
    templateId: 'LOAN_PENDING_EMAIL',
    context: {
      loanReference: context.loanReference,
      applicantName: context.applicantName
    }
  }
});

Using a Template

doCmd('SendMailToGroupCommand', {
  Data: {
    permissionCodes: ['bnk_manage_fraud_alerts'],
    subject: 'Fraud Alert Raised',
    templateId: 'FRAUD_ALERT_NOTIFICATION',
    context: {
      accountNumber: context.accountNumber,
      alertType: context.alertType,
      raisedBy: context.raisedBy
    }
  }
});

---

Notes

• Recipients with no email address set are automatically skipped.
• If no users are found matching the criteria, the command still returns isSuccessful: true with recipientCount: 0 — it is not treated as an error.
• Both the legacy RolePermission table and the newer DirectPermissions system are checked when resolving permission codes.