To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
A recurring email job which sends itself again at a fixed frequency, such as a weekly digest or a monthly statement. On top of the recipients, subject and body it inherits from BaseEmailJob, a scheduled email adds a frequency, a multiple of that frequency, an hour of the day to run at, and a start and optional end date which bound the whole schedule. Times are calculated in the owning organisation's timezone. Each run is recorded as a ScheduledEmailResult, and the next due time is worked out from the last result rather than from a stored counter, so a run which is missed does not silently shift the whole schedule. A job can also attach or link a web resource, and can run an integration pipeline whose output is attached to the email.
Group: Database Entities
Extends: BaseEmailJob
Implements: Serializable, PortableId
Properties
| Property | Returns | Description |
|---|---|---|
| active | boolean | Whether email items belonging to this job may be sent, which is true only while the schedule is enabled and not soft deleted. |
| attachHref | boolean | Whether the web resource named by the href template is attached to the email as a file. When false a link to it is inserted into the body instead. |
| enabled | boolean | Whether the schedule is switched on. A disabled job is never picked up as due, and its email items are not sent. |
| endDate | Date | When the schedule stops. Once this has passed the job is no longer picked up as due. Null means the schedule runs indefinitely. |
| frequency | Frequency | How often the job repeats: hourly, daily, weekly, monthly or annual. Combined with the period multiple to give intervals such as every three weeks. Required. |
| history | List<EmailItem> | Every email item this job has produced, newest first. This queries the database on each call and is not bounded by a date range or a result limit, so it is expensive on a long-running job; prefer findResults or a date-bounded query where you can. |
| hrefTemplate | String | Path or URL of a web resource to include with the email. It may contain template variables, so the resource can differ per recipient. Whether the resource is attached or simply linked is decided by attachHref. |
| periodMultiples | int | How many frequency periods there are between runs, so 3 with a weekly frequency means every three weeks. |
| pipeline | String | Name of an integration pipeline to run when the job fires, whose output is attached to the email. Null means no pipeline is run. |
| promotion | Reward | Reward this scheduled email promotes, linked so the email can be built around it. Lazily loaded. |
| runas | Profile | The profile recorded as the user this job runs as. Optional. |
| runHour | int | Hour of the day, from 0 to 23 in the organisation's timezone, that the job runs at. Applied to every frequency except hourly, which keeps the time of the previous run. |
| scheduledEmailResults | List<ScheduledEmailResult> | One record per run of this schedule, holding when the run started and when it completed. The next due time is derived from the most recent of these. |
| startDate | Date | When the schedule begins. The first run is this date with its time of day replaced by the run hour, so a job is never due before this. Required. |
Inherited from BaseEmailJob
Properties
| Property | Returns | Description |
|---|---|---|
| assetQueryId | String | Identifier of a query asset which selects the content the email is built from. When set, the first asset the query returns supplies the subject, from and reply-to values named by the asset field properties. |
| attachments | List<EmailJobAttachment> | Files attached to every email this job sends. Each attachment refers to blob store content by hash rather than holding the bytes. Null on a job which has never had an attachment added. |
| category | BaseEmailCategory | Category the job is filed under, used to group related jobs within an organisation. Optional. |
| deleted | Boolean | Soft deletion flag. A job with items or timers against it is flagged deleted and renamed rather than removed, so its history survives. Null means not deleted. |
| filterScriptMvel | String | Recipient filter expressed as an MVEL expression, up to 1000 characters. Recipients the expression does not evaluate to true for are dropped before sending. |
| filterScriptXml | String | Recipient filter expressed as the XML rule format, up to 1000 characters. Recipients the rule does not evaluate to true for are dropped before sending. |
| fromAddress | String | Address the emails are sent from. If blank the sender falls back to the organisation's admin domain, or to a noreply address on the primary domain. |
| fromAssetField | String | Name of the field on the asset selected by the asset query which supplies the from address, overriding the job's own from address when it resolves to a value. |
| groupRecipients | List<GroupRecipient> | The groups this job sends to. Each entry can be an exclusion instead, in which case members of that group are removed from the recipient set rather than added to it. Lazily loaded, and null on a job which has never had a group recipient added. |
| html | String | The email body, held as an MVEL template of up to 500000 characters and evaluated once per recipient. |
| id | long | Database identifier for this job. The subclasses share a single joined inheritance table, so the id is unique across scheduled emails, group emails and triggers alike. |
| loginTokens | Boolean | Whether links in the email should carry an auto-login token for the recipient, so that following one signs them in. Null is treated as false. |
| name | String | Unique, path-safe identifier for the job within its organisation, used as the lookup key and in admin URLs. Required. Soft deleting a job renames it with a '-Deleted-' suffix and a timestamp so the original name becomes available again. |
| notes | String | Free text notes about the job, up to 20000 characters. Copying a job with mimic prepends a 'Copied from' line naming the job it was copied from. |
| numEmails | Integer | Number of emails this job has queued for sending, recorded when the batch is generated so progress can be reported against it. Null before a batch has been generated. |
| organisationRecipients | List<OrganisationRecipient> | The organisations this job sends to, with the same include or exclude semantics as the group recipients. Lazily loaded, and null on a job which has never had an organisation recipient added. |
| recipientSelectors | String | Serialised recipient selection, up to 10000 characters, which is the newer replacement for the group and organisation recipient collections. |
| replyToAddress | String | Address replies are directed to. If blank the from address is used instead. |
| replyToAssetField | String | Name of the field on the asset selected by the asset query which supplies the reply-to address, overriding the job's own reply-to address when it resolves to a value. |
| subject | String | Subject line for the emails this job sends, up to 1024 characters, evaluated as an MVEL template per recipient. If it is blank the sender falls back to a generated subject built from the job title. |
| subjectAssetField | String | Name of the field on the asset selected by the asset query which supplies the subject line. Only consulted when an asset query id is set; the job subject is used if the field is empty. |
| themeSite | Website | Website whose live branch supplies the surrounding email template. When set, the generated body is wrapped in that site's email theme; when null the MVEL result is sent as-is. |
| timeToSend | Date | The time the job is intended to be sent at. Null on jobs which are not scheduled for a particular time. |
| title | String | Free text display label for the job, shown in the admin UI and used in the fallback subject line. Unlike the name it carries no uniqueness or path-safety guarantee and may be null. |
| type | String | Free text classification set by the caller and carried across when a job is copied. Not the Hibernate inheritance discriminator, which is a separate column the application does not expose. |
Methods
asGroupEmail() · asEmailTrigger() · getId() · getName() · getTitle() · getNotes() · getSubject() · getFromAddress() · getReplyToAddress() · getGroupRecipients() · getOrganisationRecipients() · getThemeSite() · getHtml() · getFilterScriptXml() · getFilterScriptMvel() · getAssetQueryId() · getSubjectAssetField() · getFromAssetField() · getReplyToAssetField() · addGroupRecipient(Group g, boolean exclusion) · getType() · getAttachments() · getLoginTokens() · getDeleted() · getNumEmails() · getTimeToSend() · getRecipientSelectors() · deleted() · getCategory() · numEmails()
asGroupEmail()
Returns: GroupEmailJob
Narrows this job to a GroupEmailJob, the one-off broadcast sent to a set of groups or organisations.
asEmailTrigger()
Returns: EmailTrigger
Narrows this job to an EmailTrigger, the event driven job which also performs non-email actions.
getId()
Returns: long
Database identifier for this job. The subclasses share a single joined inheritance table, so the id is unique across scheduled emails, group emails and triggers alike.
getName()
Returns: String
Unique, path-safe identifier for the job within its organisation, used as the lookup key and in admin URLs. Required. Soft deleting a job renames it with a '-Deleted-' suffix and a timestamp so the original name becomes available again.
getTitle()
Returns: String
Free text display label for the job, shown in the admin UI and used in the fallback subject line. Unlike the name it carries no uniqueness or path-safety guarantee and may be null.
getNotes()
Returns: String
Free text notes about the job, up to 20000 characters. Copying a job with mimic prepends a 'Copied from' line naming the job it was copied from.
getSubject()
Returns: String
Subject line for the emails this job sends, up to 1024 characters, evaluated as an MVEL template per recipient. If it is blank the sender falls back to a generated subject built from the job title.
getFromAddress()
Returns: String
Address the emails are sent from. If blank the sender falls back to the organisation's admin domain, or to a noreply address on the primary domain.
getReplyToAddress()
Returns: String
Address replies are directed to. If blank the from address is used instead.
getGroupRecipients()
Returns: List<GroupRecipient>
The groups this job sends to. Each entry can be an exclusion instead, in which case members of that group are removed from the recipient set rather than added to it. Lazily loaded, and null on a job which has never had a group recipient added.
getOrganisationRecipients()
Returns: List<OrganisationRecipient>
The organisations this job sends to, with the same include or exclude semantics as the group recipients. Lazily loaded, and null on a job which has never had an organisation recipient added.
getThemeSite()
Returns: Website
Website whose live branch supplies the surrounding email template. When set, the generated body is wrapped in that site's email theme; when null the MVEL result is sent as-is.
getHtml()
Returns: String
The email body, held as an MVEL template of up to 500000 characters and evaluated once per recipient.
getFilterScriptXml()
Returns: String
Recipient filter expressed as the XML rule format, up to 1000 characters. Recipients the rule does not evaluate to true for are dropped before sending.
getFilterScriptMvel()
Returns: String
Recipient filter expressed as an MVEL expression, up to 1000 characters. Recipients the expression does not evaluate to true for are dropped before sending.
getAssetQueryId()
Returns: String
Identifier of a query asset which selects the content the email is built from. When set, the first asset the query returns supplies the subject, from and reply-to values named by the asset field properties.
getSubjectAssetField()
Returns: String
Name of the field on the asset selected by the asset query which supplies the subject line. Only consulted when an asset query id is set; the job subject is used if the field is empty.
getFromAssetField()
Returns: String
Name of the field on the asset selected by the asset query which supplies the from address, overriding the job's own from address when it resolves to a value.
getReplyToAssetField()
Returns: String
Name of the field on the asset selected by the asset query which supplies the reply-to address, overriding the job's own reply-to address when it resolves to a value.
addGroupRecipient(Group g, boolean exclusion)
Returns: GroupRecipient
Adds a group to this job's recipient list, creating the recipient collection if the job did not have one. The new link is attached to the in-memory job only; it is not saved, so the caller must persist it.
| Parameter | Description |
|---|---|
g | the group to send to, or to exclude |
exclusion | true to exclude the group's members rather than include them |
getType()
Returns: String
Free text classification set by the caller and carried across when a job is copied. Not the Hibernate inheritance discriminator, which is a separate column the application does not expose.
getAttachments()
Returns: List<EmailJobAttachment>
Files attached to every email this job sends. Each attachment refers to blob store content by hash rather than holding the bytes. Null on a job which has never had an attachment added.
getLoginTokens()
Returns: Boolean
Whether links in the email should carry an auto-login token for the recipient, so that following one signs them in. Null is treated as false.
getDeleted()
Returns: Boolean
Soft deletion flag. A job with items or timers against it is flagged deleted and renamed rather than removed, so its history survives. Null means not deleted.
getNumEmails()
Returns: Integer
Number of emails this job has queued for sending, recorded when the batch is generated so progress can be reported against it. Null before a batch has been generated.
getTimeToSend()
Returns: Date
The time the job is intended to be sent at. Null on jobs which are not scheduled for a particular time.
getRecipientSelectors()
Returns: String
Serialised recipient selection, up to 10000 characters, which is the newer replacement for the group and organisation recipient collections.
deleted()
Returns: boolean
Null safe reading of the soft deletion flag.
getCategory()
Returns: BaseEmailCategory
Category the job is filed under, used to group related jobs within an organisation. Optional.
numEmails()
Returns: Long
The queued email count as a long, for callers which need a widened value.
Methods
asScheduledEmail() · getHrefTemplate() · isAttachHref() · getPipeline() · isEnabled() · getFrequency() · getStartDate() · getEndDate() · getPeriodMultiples() · getRunHour() · getRunas() · getPromotion() · getHistory() · getScheduledEmailResults() · findResults(Date st, Date fn) · nextRun(Date lastRun) · isActive() · portableId()
asScheduledEmail()
Returns: ScheduledEmail
Narrows this job to a ScheduledEmail, which for a scheduled email is always itself.
getHrefTemplate()
Returns: String
Path or URL of a web resource to include with the email. It may contain template variables, so the resource can differ per recipient. Whether the resource is attached or simply linked is decided by attachHref.
isAttachHref()
Returns: boolean
Whether the web resource named by the href template is attached to the email as a file. When false a link to it is inserted into the body instead.
getPipeline()
Returns: String
Name of an integration pipeline to run when the job fires, whose output is attached to the email. Null means no pipeline is run.
isEnabled()
Returns: boolean
Whether the schedule is switched on. A disabled job is never picked up as due, and its email items are not sent.
getFrequency()
Returns: Frequency
How often the job repeats: hourly, daily, weekly, monthly or annual. Combined with the period multiple to give intervals such as every three weeks. Required.
getStartDate()
Returns: Date
When the schedule begins. The first run is this date with its time of day replaced by the run hour, so a job is never due before this. Required.
getEndDate()
Returns: Date
When the schedule stops. Once this has passed the job is no longer picked up as due. Null means the schedule runs indefinitely.
getPeriodMultiples()
Returns: int
How many frequency periods there are between runs, so 3 with a weekly frequency means every three weeks.
getRunHour()
Returns: int
Hour of the day, from 0 to 23 in the organisation's timezone, that the job runs at. Applied to every frequency except hourly, which keeps the time of the previous run.
getRunas()
Returns: Profile
The profile recorded as the user this job runs as. Optional.
getPromotion()
Returns: Reward
Reward this scheduled email promotes, linked so the email can be built around it. Lazily loaded.
getHistory()
Returns: List<EmailItem>
Every email item this job has produced, newest first. This queries the database on each call and is not bounded by a date range or a result limit, so it is expensive on a long-running job; prefer findResults or a date-bounded query where you can.
getScheduledEmailResults()
Returns: List<ScheduledEmailResult>
One record per run of this schedule, holding when the run started and when it completed. The next due time is derived from the most recent of these.
findResults(Date st, Date fn)
Returns: List<ScheduledEmailResult>
Queries the run records for this schedule which fall within a date range, using the current session.
| Parameter | Description |
|---|---|
st | start of the date range |
fn | end of the date range |
nextRun(Date lastRun)
Returns: Date
Works out when this schedule is next due, in the organisation's timezone. With no previous run it returns the start date moved to the configured run hour; otherwise it advances the last run by the frequency and period multiple, and resets the hour of day to the run hour for every frequency except hourly.
| Parameter | Description |
|---|---|
lastRun | when the schedule last ran, or null if it never has |
isActive()
Returns: boolean
Whether email items belonging to this job may be sent, which is true only while the schedule is enabled and not soft deleted.
portableId()
Returns: String
The identifier used when moving this job between accounts, which is its name rather than its database id.
© 2025 Kademi Ltd