Broadcasts & Notifications

Send engage campaigns over email, messenger, and SMS, and deliver in-app and email notifications to team members.

For inbound mail, DKIM, and the mail worker, see Email Delivery.

Broadcasts

backend/core-api/src/modules/broadcast/:

graphql/schemas/{index,engage}.ts
graphql/resolvers/{queries,mutations,customResolvers}/
db/definitions/{engages,deliveryReports,broadcastTraces,smsRequest,log,common}.ts
db/models/{Engages,DeliveryReports,BroadcastTraces,SmsRequests,Logs,factories}.ts
worker/{broadcast,email,messenger,notification,index}.ts
trackers/{engage,sendgrid,index}.ts
routes/{index,telnyx,tracker,unsubscribe}.ts
utils/{broadcast,email,engage,outboundEmail,sender,targeting,
      telnyx,transporter,worker,widget,...}.ts
trpc/{broadcast,index}.ts

An EngageMessage (engages.ts) carries kind (auto, visitorAuto, manual), method (messenger, email, notification), title, fromEmail, fromUserId, cpId, targetType/targetIds/targetCount, isDraft, isLive, channel payloads (email, messenger, notification), plus send progress (totalBatches, processedBatches, successCount, failureCount, lastUpdated) and status (sending, completed, failed).

GraphQL API

Operation	Key arguments
engageMessages	kind, status, method, brandId, fromUserId, searchValue, cursor params; returns EngageMessageListResponse
engageMessageDetail / engageMessagesTotalCount	_id / same filters
engageMessageCounts	name!, kind, status
engageMembers	isVerified, cursor params
engageReportsList	page, perPage, customerId, status, searchValue; returns EngageDeliveryReport
engageSmsDeliveries	type!, to, page, perPage
engageBroadcastTraces	engageMessageId!
engageEmailPercentages, engageVerifiedEmails, engagesConfigDetail, emailSenderOptions	scope for the last
engageMessageAdd / engageMessageEdit	title, kind, method, fromEmail, fromUserId, cpId, targetType, targetIds, targetCount, isDraft, isLive, email, messenger, notification
engageMessageSetLive / SetPause / SetLiveManual	_id!
engageMessageRemove / engageMessageCopy	_ids / _id!
engageMessageVerifyEmail / engageMessageRemoveVerifiedEmail	email!, name, replyTo, scope / email!, scope
engageMessageSendTestEmail	from!, to!, content!, title!
engagesUpdateConfigs / broadcastUpdateConfigs	configsMap: JSON!
engageSendMail	integrationId, conversationId, subject!, body, to: [String]!, cc, bcc, from!

Delivery pipeline

Sending runs through worker/ batch processors (broadcast, email, messenger, notification); a broadcast is not transactional: create it, set it live, then track per-recipient state in DeliveryReports, BroadcastTraces, SmsRequests, and Logs. Open/click tracking lands via routes/tracker.ts and trackers/; Telnyx webhooks arrive on routes/telnyx.ts; unsubscribe links hit routes/unsubscribe.ts. Outbound email builds SES headers in utils/email.ts (X-SES-CONFIGURATION-SET, default config set erxes) and sends through the SES transporter in utils/transporter.ts (AWS_SES_ACCESS_KEY_ID, AWS_SES_SECRET_ACCESS_KEY).

Notifications

backend/core-api/src/modules/notifications/:

graphql/schema/{index,subscription}.ts
graphql/resolver/{queries,mutations,utils}.ts
graphql/customResolvers/{notification,emailAddress}.ts
db/models/{EmailSenders,EmailAddresses,EmailDeliveries,EmailRamp}.ts
trpc/{email,index}.ts
routes/{index,senderConfirm}.ts

Notification records, settings, and the outbound-email pipeline (senders, addresses, deliveries, ramp) share one module. In-app delivery uses the notificationInserted GraphQL subscription:

subscription OnNotification($id: String!) {
  notificationInserted(_id: $id) { _id }
}

Operation	Key arguments
notifications	ids, status (READ/UNREAD/ALL), priority (LOW/MEDIUM/HIGH/URGENT), type (INFO/SUCCESS/WARNING/ERROR), fromDate, endDate, fromUserId, module, cursor params
notificationDetail / unreadNotificationsCount	_id! / none
pluginsNotifications	none; returns every plugin's declared modules/events
notificationSettings	none; returns the per-user event/channel matrix
emailDeliveries / emailDeliveryDetail	status, source, provider, searchValue, date range, cursor params / _id!
emailAddresses	lane, suppressionReason, searchValue, emails, cursor params
emailRampStatus	none
markNotificationAsRead / markAsReadNotifications	_id! / notification filters
archiveNotification / archiveNotifications	_id! / ids, archiveAll, filters
updateNotificationSettingsEvent / Channel	input: { event, enabled, channels } / input: { channel, enabled, metadata }
emailAddressRelease / emailRampRelease	email!, note! / note!

How plugins register notifications

A plugin declares its notification modules and events in src/meta/notifications.ts:

// backend/plugins/sales_api/src/meta/notifications.ts (trimmed)
export const notifications = {
  plugin: 'sales',
  modules: [
    {
      name: 'deals',
      description: 'Deals',
      icon: 'IconChecklist',
      events: [
        { name: 'dealAssignee', title: 'Deal assignee', description: 'Triggered when a user is assigned to a deal' },
      ],
    },
  ],
};

pluginsNotifications merges these with CORE_NOTIFICATION_MODULES (modules/notifications/constants.ts) for the settings UI, where users toggle events and channels via updateNotificationSettingsEvent. To emit, a plugin calls sendNotification(subdomain, { userIds, kind, notificationType, ... }) from erxes-api-shared/core-modules; it validates the payload, creates the in-app record over tRPC (module: 'notifications', action: 'create'), then sendNotificationChannels fans out to email (sendNotificationEmail) when the user has that channel enabled. Frontend plugins render entries in their own notification widgets under frontend/libs/ui-modules / plugin NotificationsWidgets.

The email path is detailed in Email Delivery: EmailSenders (verified from-addresses, senderConfirm route), EmailAddresses (suppression lanes; release with emailAddressRelease), EmailDeliveries (per-message state), EmailRamp (sending warmup; release with emailRampRelease).

Permissions

broadcastRead (always), broadcastCreate, broadcastUpdate, broadcastDelete, broadcastConfigsManage; scope own (records in createdBy) or all. Notifications have no admin actions: users manage only their own feed and settings.

Example

mutation SendTest {
  engageMessageSendTestEmail(
    from: "[email protected]"
    to: ["[email protected]"]
    title: "Test"
    content: "<p>Hello</p>"
  )
}

query MyNotifications {
  notifications(status: UNREAD, limit: 20) {
    list { _id }
    totalCount
  }
}