To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Owns creation, sending and tracking of EmailItems, and is reached from server-side JS as services.emailManager. A developer starts a new email with emailBuilder, which returns an EmailItemBuilder to set the recipient, sender, subject and body before building and sending it. The manager also finds recipients and jobs for group and automated emails, tracks delivery, read and conversion status for individual items, and reports role checks for who may administer, edit or send email and view its recipients. It starts and stops the underlying mail server, and its background acknowledgement queue, as part of the application lifecycle.
Group: Managers
Implements: StartableService
Properties
| Property | Returns | Description |
|---|---|---|
| automationEmailLimit | Integer | The maximum number of recipients allowed for a single automated email, for the current tenant organisation. |
| emailTemplates | List | Finds the group email jobs stored as templates for the current tenant organisation. This is a database lookup. |
| groupEmailLimit | Integer | The maximum number of recipients allowed for a single group email, as configured for the email app on the current tenant. |
Methods
findRecipients(BaseEmailJob job) · findRecipients(BaseEmailJob job, JobStatus jobStatus) · findByDate(Date start, Date finish) · findGroupEmailsByOrg() · getGroupEmailLimit() · emailBuilder() · getEmailTemplates() · emailSearch(String q, Long funnelId, BaseEmailJob job, Date startDate, Date endDate, Integer startRow, Integer maxSize) · findJobsByDate(Date startDate, Date finish) · emailStatsDb(BaseEmailJob j, Date startDate, Date finish) · emailStats(BaseEmailJob j, Date startDate, Date endDate) · getEmailContent(EmailItem emailItem) · parseEmailAddress(String emailAddress) · emailItemUpdated(EmailItem emailItem) · updateEmailComplete(EmailItem emailItem, boolean fireEvent) · updateEmailFailed(EmailItem emailItem, boolean fireEvent) · updateEmailOpened(EmailItem emailItem, boolean fireEvent) · updateEmailConverted(EmailItem emailItem, boolean fireEvent) · createSendAttempt(EmailItem emailItem) · sendAttemptUpdated(EmailSendAttempt esa) · getAutomationEmailLimit() · getAutomationEmailLimit(Organisation adminOrg) · createEmailTemplate(String templateName, String title, String subject, String emailBody, Website website) · findGroupEmailType(String type) · addGroupRecipient(BaseEmailJob emailJob, Group group, boolean exclusion) · removeGroupRecipient(BaseEmailJob emailJob, Group group, boolean exclusion) · addOrganisationRecipient(BaseEmailJob emailJob, Organisation organisation, boolean exclusion) · removeOrganisationRecipient(BaseEmailJob emailJob, Organisation organisation, boolean exclusion) · findBaseEmailJobById(Long id) · isEmailAdministrator(Profile profile) · isEmailEditor(Profile profile) · isEmailSender(Profile profile) · canViewRecipients(Profile profile)
findRecipients(BaseEmailJob job)
Returns: List<ExtProfileBean>
Finds the profiles who will receive the given email job, after applying group or scheduled recipient rules and filtering out any without an email address. This is a database lookup and can be expensive for large recipient sets.
| Parameter | Description |
|---|---|
job | the group or scheduled email job to find recipients for |
findRecipients(BaseEmailJob job, JobStatus jobStatus)
Returns: List<ExtProfileBean>
Finds the profiles who will receive the given email job, after applying group or scheduled recipient rules and filtering out any without an email address, reporting progress through the given job status. This is a database lookup and can be expensive for large recipient sets.
| Parameter | Description |
|---|---|
job | the group or scheduled email job to find recipients for |
jobStatus | receives progress updates while recipients are being resolved |
findByDate(Date start, Date finish)
Returns: List<GroupEmailJob>
Finds group email jobs for the current tenant organisation with a status date within the given range, excluding templates. This is a database lookup over all of the organisation's group email jobs.
| Parameter | Description |
|---|---|
start | the earliest status date to include, exclusive |
finish | the latest status date to include, exclusive |
findGroupEmailsByOrg()
Returns: List<GroupEmailJob>
Finds the non-template group email jobs for the current tenant organisation. This is a database lookup.
getGroupEmailLimit()
Returns: Integer
The maximum number of recipients allowed for a single group email, as configured for the email app on the current tenant.
emailBuilder()
Returns: EmailItemBuilder
Creates a new EmailItemBuilder for the current tenant organisation, used to set the recipient, sender, subject and body of an email before building and sending it.
getEmailTemplates()
Returns: List
Finds the group email jobs stored as templates for the current tenant organisation. This is a database lookup.
emailSearch(String q, Long funnelId, BaseEmailJob job, Date startDate, Date endDate, Integer startRow, Integer maxSize)
Returns: KSearchResponse
Searches indexed email items in elasticsearch, optionally filtered by free text over the from address, recipient address and subject, by funnel, by job and by a created date range. Results are sorted by created date, descending. This is a search index query, not a direct database read.
| Parameter | Description |
|---|---|
q | free text to search for across the from address, recipient address and subject, or null or blank to skip text filtering |
funnelId | restricts results to email items linked to this funnel, or null to skip this filter |
job | restricts results to email items belonging to this email job, or null to skip this filter |
startDate | restricts results to items created on or after this date, or null to skip this bound |
endDate | restricts results to items created on or before this date, or null to skip this bound |
startRow | unused by the current implementation, present for future paging support |
maxSize | unused by the current implementation, present for future paging support |
findJobsByDate(Date startDate, Date finish)
Returns: List<BaseEmailJob>
Finds email jobs for the current tenant organisation with a status date within the given range. This is a database lookup.
| Parameter | Description |
|---|---|
startDate | the earliest status date to include |
finish | the latest status date to include |
emailStatsDb(BaseEmailJob j, Date startDate, Date finish)
Returns: EmailStatusCounts
Counts email items for a job within a date range, split by send status, read status and conversion status. This is a query on the primary database rather than the search index, so it does not apply an organisation hierarchy filter, but it is the most authoritative source of counts.
| Parameter | Description |
|---|---|
j | restricts the count to email items belonging to this job, or null to count across all jobs |
startDate | restricts the count to items created on or after this date, or null to skip this bound |
finish | restricts the count to items created on or before this date, or null to skip this bound |
emailStats(BaseEmailJob j, Date startDate, Date endDate)
Returns: EmailStatusCounts
Counts email items for a job within a date range, split by send status, read status and conversion status. This is a search index query restricted to organisations within the current selected organisation hierarchy, unlike emailStatsDb which queries the primary database without that filter.
| Parameter | Description |
|---|---|
j | restricts the count to email items belonging to this job, or null to count across all jobs |
startDate | restricts the count to items created on or after this date, or null to skip this bound |
endDate | restricts the count to items created on or before this date, or null to skip this bound |
getEmailContent(EmailItem emailItem)
Returns: EmailContent
Retrieves the stored HTML and text content for an email item, using the currently registered content service.
| Parameter | Description |
|---|---|
emailItem | the email item to read content for |
parseEmailAddress(String emailAddress)
Returns: MailboxAddress
Parses an email address string, which may carry a display name, into a MailboxAddress.
| Parameter | Description |
|---|---|
emailAddress | the address to parse, such as "Joe Bloggs less-than joe at bloggs.com greater-than" or a bare address |
emailItemUpdated(EmailItem emailItem)
Returns: void
Saves an email item and fires an indexed-item-updated event so the search index picks up its new state.
| Parameter | Description |
|---|---|
emailItem | the email item that was changed |
updateEmailComplete(EmailItem emailItem, boolean fireEvent)
Returns: void
Marks an email item as sent, recording the send status and its date, and saves it. Optionally fires an EmailDeliveryEvent so listeners can react to the delivery.
| Parameter | Description |
|---|---|
emailItem | the email item that was delivered |
fireEvent | true to fire an EmailDeliveryEvent for the delivery |
updateEmailFailed(EmailItem emailItem, boolean fireEvent)
Returns: void
Marks an email item as failed to send, recording the send status and its date, and saves it. Optionally fires an EmailDeliveryEvent so listeners can react to the failure.
| Parameter | Description |
|---|---|
emailItem | the email item that failed to send |
fireEvent | true to fire an EmailDeliveryEvent for the failure |
updateEmailOpened(EmailItem emailItem, boolean fireEvent)
Returns: void
Marks an email item as read and saves it. Optionally fires an EmailDeliveryEvent so listeners can react to the open.
| Parameter | Description |
|---|---|
emailItem | the email item that was opened |
fireEvent | true to fire an EmailDeliveryEvent for the open |
updateEmailConverted(EmailItem emailItem, boolean fireEvent)
Returns: void
Marks an email item as read and converted, and saves it. Optionally fires an EmailDeliveryEvent for the open and, if the item is linked to a funnel lead, updates that lead so its engagement score reflects the conversion.
| Parameter | Description |
|---|---|
emailItem | the email item that was converted |
fireEvent | true to fire an EmailDeliveryEvent and update any linked lead |
createSendAttempt(EmailItem emailItem)
Returns: EmailSendAttempt
Creates and saves a new EmailSendAttempt for an email item, recording it against the item's list of send attempts.
| Parameter | Description |
|---|---|
emailItem | the email item a send is being attempted for |
sendAttemptUpdated(EmailSendAttempt esa)
Returns: void
Saves changes to an existing send attempt.
| Parameter | Description |
|---|---|
esa | the send attempt that was changed |
getAutomationEmailLimit()
Returns: Integer
The maximum number of recipients allowed for a single automated email, for the current tenant organisation.
getAutomationEmailLimit(Organisation adminOrg)
Returns: Integer
The maximum number of recipients allowed for a single automated email, for the given organisation.
| Parameter | Description |
|---|---|
adminOrg | the organisation to look up the limit for |
createEmailTemplate(String templateName, String title, String subject, String emailBody, Website website)
Returns: GroupEmailJob
Creates and saves a new group email job of type TEMPLATE for the current tenant organisation, and reports the creation to account telemetry.
| Parameter | Description |
|---|---|
templateName | the internal name of the template, used to identify it |
title | the display title of the template |
subject | the email subject line for messages built from this template |
emailBody | the HTML body of the template |
website | the website the template is themed against |
findGroupEmailType(String type)
Returns: GroupEmailType
Parses a group email type from its name.
| Parameter | Description |
|---|---|
type | the name of the group email type, such as "TEMPLATE" or "EMAIL" |
addGroupRecipient(BaseEmailJob emailJob, Group group, boolean exclusion)
Returns: GroupRecipient
Adds a group to an email job's recipient list and saves the new recipient link.
| Parameter | Description |
|---|---|
emailJob | the email job to add the group recipient to |
group | the group to add |
exclusion | true means the group is excluded, so its members must not receive the email |
removeGroupRecipient(BaseEmailJob emailJob, Group group, boolean exclusion)
Returns: void
Removes a group from an email job's recipient list.
| Parameter | Description |
|---|---|
emailJob | the email job to remove the group recipient from |
group | the group to remove |
exclusion | true means the group was excluded, so its members were not receiving the email |
addOrganisationRecipient(BaseEmailJob emailJob, Organisation organisation, boolean exclusion)
Returns: OrganisationRecipient
Adds an organisation to an email job's recipient list and saves the new recipient link.
| Parameter | Description |
|---|---|
emailJob | the email job to add the organisation recipient to |
organisation | the organisation to add |
exclusion | true means the organisation is excluded, so its members must not receive the email |
removeOrganisationRecipient(BaseEmailJob emailJob, Organisation organisation, boolean exclusion)
Returns: void
Removes an organisation from an email job's recipient list.
| Parameter | Description |
|---|---|
emailJob | the email job to remove the organisation recipient from |
organisation | the organisation to remove |
exclusion | true means the organisation was excluded, so its members were not receiving the email |
findBaseEmailJobById(Long id)
Returns: BaseEmailJob
Finds the email job with the given ID belonging to the current tenant organisation. This is a database lookup.
| Parameter | Description |
|---|---|
id | the ID of the email job to find |
isEmailAdministrator(Profile profile)
Returns: boolean
Checks whether a profile holds the admin or email administrator role.
| Parameter | Description |
|---|---|
profile | the profile to check |
isEmailEditor(Profile profile)
Returns: boolean
Checks whether a profile holds the admin, email administrator or email editor role.
| Parameter | Description |
|---|---|
profile | the profile to check |
isEmailSender(Profile profile)
Returns: boolean
Checks whether a profile holds the admin, email administrator, email editor or email sender role.
| Parameter | Description |
|---|---|
profile | the profile to check |
canViewRecipients(Profile profile)
Returns: boolean
Checks whether a profile holds the admin, user administrator or user viewer role.
| Parameter | Description |
|---|---|
profile | the profile to check |
© 2025 Kademi Ltd