Creating Emails in Rulesets

Updated pdexter 2025-06-05

Emails can be created and sent via the ruleset include "Email Functions JS".

As of approx May 2025, email creation can be done via the Formbird Email Queue system, which uses an Email Message document and system actions to retry email sending, in the case that the email service is not available in the first instance.

For backward compatibility, the older functions will work without changes to the function signature (ie how it's coded) and without queueing.

The following information relates to new Email and Email Functions as of June 2025, of release Email Template & Email Queue v202506A Prior function syntax has been maintained for older usages.

Initialising

In order to utilise Email Functions, include it in your ruleset

{ 
...
#include "Email Functions JS",

...
}

The main object which contains all Email functions is simply "ft3.emailFunctions".

Sending an Email (without queueing)

A number of functions are available for emailing without queueing.

Examples

#include "JayRule Ruleset Overlay",
#include "Email Functions JS",
...

        ruleSendEmail : {
            ruleCondition : true,

            ruleAction : async function(ntf) {
                const ft3 = ntf.scope;

                // Get formbird attachments from sc-uploader field on document.
                const fbAttachments = ntf.document.releaseFiles || [];

                // Create attachments from scratch
                const attachments = [ 
                    {
                        content: `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`,
                        filename: "sample.txt",
                        type: "text/plain",
                        disposition: "attachment"
                    }
                ];

                const from = null;
                const to = 'peter.dexter@formbird.com';
                const cc = [];
                const bcc = [];
                const htmlContent = '<div>what is going on </div>';
                const subject = 'Message from ' + ntf.document.commonName;

                ft3.emailFunctions.sendEmail(ntf, to, cc, bcc, subject, htmlContent, fbAttachments, attachments);
                // OR
                ft3.emailFunctions.sendFormbirdEmail(ntf, to, cc, bcc, subject, htmlContent, fbAttachments, attachments);   
            }
        },

To send without any Formbird attachments or scratch built attachments:

ft3.emailFunctions.sendEmail(ntf, to, cc, bcc, subject, htmlContent);
ft3.emailFunctions.sendFormbirdEmail(ntf, to, cc, bcc, subject, htmlContent);

To send with only Formbird attachments:

ft3.emailFunctions.sendEmail(ntf, to, cc, bcc, subject, htmlContent, fbAttachments);
ft3.emailFunctions.sendFormbirdEmail(ntf, to, cc, bcc, subject, htmlContent, fbAttachments);

To send with only scratch built attachments:

ft3.emailFunctions.sendEmail(ntf, to, cc, bcc, subject, htmlContent, [], attachments);
ft3.emailFunctions.sendFormbirdEmail(ntf, to, cc, bcc, subject, htmlContent, [], attachments);

Sending an Email with queueing

New functions recently added for utilising the Formbird Email Queue system (FEQS).

Syntax

var result = await ft3.emailFunctions.queueEmail( ntf, emailOptions );

with emailOptions being

{ to : single or array of target email addresses, cc : single or array of target email addresses,
bcc : single or array of target email addresses, subject : subject of email, message : text or html of email content, formbirdAttachments : array of formbird attachments, or reference to sc-uploader, attachments: array of scratch built attachments }

Other functions have also been "retrofitted" to use the email queueing system.

#include "JayRule Ruleset Overlay",
#include "Email Functions JS",
...
    ruleSendQueuedEmail : {
        ruleCondition : true,

        ruleAction : async function(ntf) {
            const ft3 = ntf.scope;

            // Get formbird attachments from sc-uploader field on document.
            const fbAttachments = ntf.document.releaseFiles || [];

            // Create attachments from scratch
            const attachments = [ 
                {
                    content: `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`,
                    filename: "sample.txt",
                    type: "text/plain",
                    disposition: "attachment"
                }
            ];

            const messageOB = {
                to : 'peter.dexter@formbird.com', 
                cc : [],
                bcc : [], 
                subject : 'Message from ' + ntf.document.commonName,
                message : '<div>Here be the message to you</div>',
                formbirdAttachments : fbAttachments,
                attachments : attachments
            };

            var result = await ft3.emailFunctions.queueEmail(ntf, messageOB);
            // OR
            const useFEQ = true;
            await ft3.emailFunctions.sendFormbirdEmail(ntf, messageOB.to, messageOB.cc, messageOB.bcc, messageOB.subject, messageOB.message, fbAttachments, attachments, useFEQ);   

        }
    },

Using Email Templates

Email Templates can be used by a number of functions.

The defining of Email Templates is explained in more detail in Creating Emails with Email Templates.

launchEmail

Syntax

ft3.emailFunctions.launchEmail( ntf, emailTemplate, replacements, function(e) { ... });

OR

ft3.emailFunctions.launchEmail( ntf, emailTemplate, replacements, formbirdAttachments, function(e) { ... });

OR

ft3.emailFunctions.launchEmail( ntf, emailTemplate, replacements, formbirdAttachments, attachments, function(e) { ... });

Example

{
#include "JayRule Ruleset Overlay JS",
#include "Email Functions JS",

    ruleset : {
        ...

        // -------------------------------------------------------------------
        // Rule "Water On Alerting"
        // -------------------------------------------------------------------
        ruleWaterOnAlert : {
            ruleCondition : function(ntf) {
                ...
            },

            ruleAction : function(ntf, callback) {
                var ft3 = ntf.scope; 
                ntf.logger.info('Minimum expected water off reached.');

                var emailTemplate = 'Barwon Water On Alert';
                var calcDateM = ft3.moment(ntf.document.completed);
                var calcDateStr = calcDateM.format('DD MMM YYYY, h:mm a');

                var replacements = {
                    'urlRoot'           : ntf.urlRoot,
                    'completedDate'     : calcDateStr
                };

                var fbAttachments = ntf.document.resourceFiles || []; // sc-uploader

                ft3.emailFunctions.launchEmail(ntf, emailTemplate, replacements, fbAttachments, function(errMsg) {
                    if (errMsg) {
                        ntf.logger.info(errMsg);
                    }
                    else {
                        ntf.logger.info('Email sent ok.');

                        ntf.document.waterOnNotificationSentTS = ft3.moment().toISOString();
                    }
                    callback();
                });
            }
        },

        ...
    }
}

queueEmailFromTemplate

Syntax

var result = await ft3.emailFunctions.queueEmailFromTemplate(ntf, { emailTemplateName : (name of email template (etName)), replacements : { object of key-value, to replace "{{key}}" in email template with value }, formbirdAttachments : array of formbird attachments / reference to sc-uploader field, attachments : array of scratch built attachments });

Example

{
#include "JayRule Ruleset Overlay JS",
#include "Email Functions JS",
...

    ruleSendEmail : {
        ruleCondition : true,

        ruleAction : async function(ntf) {
            const ft3 = ntf.scope;

            var attachments = [ 
                {
                    content: `Lorem ipsum dolor sit amet, consectetur adipiscing ... id est laborum.`,
                    filename: "sample.txt",
                    type: "text/plain",
                    disposition: "attachment"
                }
            ];

            var result = await ft3.emailFunctions.queueEmailFromTemplate(ntf, {
                emailTemplateName : 'AAAA Test Email',
                replacements : {},
                formbirdAttachments : ntf.document.releaseFiles || [],
                attachments : attachments
            });

            ntf.logger.info(`Result: ${JSON.stringify(result)}`);

            return;
        }
    },