Toggle menu

sendmail

The sendemail method sends emails to the addresses supplied as an array of address objects. Emails can be sent as plain text or HTML. The email body can be supplied directly as a text or HTML string, or be built from a data object supplied to a Handlebars template.

The only required properties are "to", "subject" and "body". Many of the properties set in the worker configuration can also be overridden.

Limits

All mail servers put limits on the total size of the emails they will accept. In AWS (our main hosting provider) the size limit is 40MB after encoding for the complete email, including embedded images and attachments.

There is also a limit of 50 recipients for a single message (combined "to", "cc" and "bcc"). When sending emails you should be emailing each recipient individually. The use cases for recipients having a message with the same message-id are limited to situations in which the recipients are expected to interact with the message as a group, for example, recipients using reply-all to the email and having a resulting email conversation.

Parameters

NameTypeDescription
toArray, requiredAn array of address objects
ccArray, optionalAn array of address objects
bccArray, optionalAn array of address objects
fromObject, optionalA single address object. If not set will use the address from the worker.conf
replyToArray, optionalAn array of address objects
subjectObject, requiredAn object with the following properties
subject.textString, requiredThe email subject. Can be a simple string or Handlebars template
subject.useHandlebarsBoolean, optionalIf subject.text includes Handlebars notation, defaults to true if omitted. That is, if you want to send content that includes braces, set this as false to prevent the content from being treated as a Handlebars template
bodyObject, requiredEither text or html must be supplied
body.textString, optionalThe email body. Can be a simple string or Handlebars template
body.htmlString, optionalThe email body. Can be a simple string or Handlebars template
body.useHandlebarsBoolean, optionalIf body.text or body.html includes Handlebars notation, defaults to true if omitted. That is, if you want to send content that includes braces, set this as false to prevent the content from being treated as a Handlebars template
body.analyticsObject, optionalAdd Google Analytics tracking to email
attachmentsArray, optionalAn array of FileReference objects
dataObject, optionalRequired if using JSONPath objects in your address objects or if using Handlebars in subject or body
data.srcObject or string, required if using a data objectEither a FileReference object or string of iCM Bulk Mail rule IDs
data.rootObject, required if using a data objectA JSONPath object
data.root.pathString, required if using a data objectThe path to the root of the data. This should return a single object or an array. An email will be sent to each
data.csvObject, optionalAdditional processing if the src contains csv values
data.csv.skipInteger, optionalRows to skip at the top of the file. Default 0
data.csv.headerBoolean, optionalDoes the first row contain header names? Default false. If true the resulting JSON can be accessed as col0, col1, col2 etc
data.csv.sepString, optionalA custom separator. Defaults to ,
data.csv.quoteString, optionalA custom quote character. Defaults to "
helpersObject, optionalA FileReference object containing Handlebars helper definitions
SMTPServerString, optionalWill use the value from worker.conf if not set
SMTPPortInteger, optionalWill use the value from worker.conf if it exists
SMTPAuthBoolean, optionalWill use the value from worker.conf if it exists
SMTPTLS_SSLString, optionalWill use the value from worker.conf if it exists
SMTPUserString, optionalWill use the value from worker.conf if it exists
SMTPPasswordString, optionalWill use the value from worker.conf if it exists
bounceToString, optionalWill use the value from worker.conf if it exists

Full Parameter Structure

{
    "to": [],
    "cc": [],
    "bcc": [],
    "from": {},
    "replyTo": [],
    "subject": {
        "text": "",
        "useHandlebars": true
    },
    "body": {
        "text": "",
        "html": "",
        "useHandlebars": true,
        "analytics": {
            "tid": "",
            "cid": "",
            "uid": "",
            "dp": "",
            "campaign": {
                "cs": "",
                "cm": "",
                "cn": "",
                "metrics": [],
                "addToLinks": ""
            }
        }
    },
    "attachments": [],
    "data": {
        "src": {},
        "root": {
            "path": ""
        },
        "csv": {
            "skip": 1,
            "header": true,
            "sep": ",",
            "quote": "'"
        }
    },
    "helpers": {},
    "SMTPServer": "",
    "SMTPPort": 25,
    "SMTPAuth": false,
    "SMTPTLS_SSL": "TLS",
    "SMTPUser": "",
    "SMTPPassword": "",
    "bounceTo": ""
}

Returns

PropertyTypeDescription
messagesStringAny error messages
failedIntegerThe number of failed emails
sentIntegerThe number sent

JSONPath Objects

JSONPath objects can be used in dynamic fields, most commonly in address objects. A single JSONPath object also sets the root object or list in the data object from a FileReference. See the sections below for examples.

A JSONPath object includes a single property - path

Full details of the syntax is available at https://github.com/jayway/JsonPath

Address Objects

Address objects are used to store an email address and a friendly alias. You can supply values for each as a string, or as a JSONPath object (relative to the data.root.path) to a value in a FileReference object set in the data.src property.

Example 1 - Supplied Directly

In this example the values of the address objects are supplied as strings:

"to": [{   
    "address": "b.smith@somewhere.com",
    "name": "Bob"
}, {  
    "address": "t.brown@somewhereelse.com",
    "name": "Tim"
}]

Example 2 - JSONPath to FileReference

JSONPath objects can be used to set the values of the address and name:

{
    "to": [{  
        "address": {    
            "path": "email"  
        },
          "name": {    
            "path": "name"  
        }
    }],
    "subject": {
        "text": "The email subject"
    },
    "body": {
        "html": "<p>The email body</p>"
    },
    "data": {
        "src": {
            "refType": "URL",
            "ref": "http://timssite/media/examplejsonaddresses.json"
        },
        "root": {
            "path": "$.addressData"
        }
    }
}

where the following is supplied as a FileReference via data.src:

{
    "addressData": [{
        "name": "Bob",
        "email": "b.smith@gmail.com"
    }, {
        "name": "Tim",
        "email": "tim@gmail.com"
    }]
}

Example 3 - Bulk Mail Rules

The Email worker can also send emails using the Bulk Mail rules set up in iCM. The data.src is the ID of a mailing rule.

Note that ObjectData.EMAIL uses the name of the field in your site userprofile that hold's the user's email address (by convention called EMAIL, but check this is true for your installation).

{
    "to": [{
        "address": {
            "path": "ObjectData.EMAIL"
        }
    }],
    "subject": {
        "text": "The email subject"
    },
    "body": {
        "html": "<p>The email body</p>"
    },
    "data": {
        "src": "19641",
        "root": {
            "path": "$"
        }
    }
}

FileReference Objects

FileReference objects are used to describe the files that will be added as attachments, Handlebars helpers, and the data object files that supply values to the dynamic fields of the email. There are five types of FileReference, each describing a different source for a file.

FileReference Object{
  "refType":"", //One of "PATH", "URL", "UUID", "MEDIA" or "PDF"
  "ref":"", //The reference (source), see below
  "name":"" //Optional - Only used for attachments. If not supplied the actual file name will be used
}

PATH

An absolute UNC path to a file. The API Server must have read access.

{
    "refType": "PATH",
    "ref": "c:\media\examplejsonaddresses.json",
    "name": "examplejsonaddresses.json"
}

URL

An absolute URL to the file. The URL must allow anonymous read access.

{
    "refType": "URL",
    "ref": "http://myssite/examplejsonaddresses.json",
    "name": "examplejsonaddresses.json"
}

UUID

The UUID of a file stored in the API Server's file store (created by the File Store worker).

{
    "refType": "UUID",
    "ref": "0C87C153-08BE-44FE-A78A-5857F4A42B7A"
}

MEDIA

The ID of an iCM media item and optional media component separated by a pipe | character. If the component isn't set and more than one file is returned only the first will be used.

{
    "refType": "MEDIA",
    "ref": "48|image",
    "name": "picture.jpeg"
}

PDF

A Handlebars template which will be compiled and populated from the supplied data, converted to a PDF and attached to the email. The PDF will use the "name" property.

{
    "refType": "PDF",
    "ref": "<p>Some HTML including Handlebars templating delivered to {{name}}</p>",
    "name": "example.pdf"
}

Handlebars

The worker uses Handlebars to provide a templating system that allows you to customise emails with details from the data object. The worker uses Handlebars.java (version 4.3.0 at the time of writing https://github.com/jknack/handlebars.java) which has several built in helpers that are functionally equivalent to the helpers in Handlebars.js. If you wish to supply your own helpers you can add them to a standard JavaScript file and include them as a FileReference using the helpers property.

Google Analytics

The analytics object allows you to use Google's Email Tracking Measurement Protocol to measure user interactions with your email. Documentation for the various fields can be found at https://developers.google.com/analytics/devguides/collection/protocol/v1/email.

Note that while the Email worker provides the ability to set the following properties, we do not offer support or consultancy in using email tracking or Google Analytics.

Properties

The analytics object is part of the email body object. The worker automatically adds the t, ec, ea and dt parameters and if you supply a campaign object it will add the campaign fields to each link on your email automatically.

NameTypeDescription
analyticsObjectAn object with the following properties
analytics.tidString, requiredThe tracking ID. Use the tracking ID of your site
analytics.cidString, optionalA client ID. If missing a random UUID will be supplied
analytics.uidString, optionalA user ID string or JSONPath object representing a unique ID for each email
analytics.dpString, optionalGoogle recommend using /email/
analytics.campaignObject, optionalProvides campaign tracking, made up of the following properties
analytics.campaign.csStringThe campaign source
analytics.campaign.cmStringThe campaign medium
analytics.campaign.cnStringThe campaign name
analytics.campaign.metricsArrayAn array of custom metrics (strings)
analytics.campaign.addToLinksStringAny links to this URL will have campaign tags added

Complete Examples

Using a Data File with Handlebars Templates and a JSONPath Address Object

The examplejsonaddresses.json file in the example below contains the following:

{
    "addressData": [{
        "name": "Bob",
        "email": "b.smith@gmail.com"
    }, {
        "name": "Tim",
        "email": "tim@gmail.com"
    }]
}

The Email worker is being used in an End Point. Two emails will be sent, one to Tim and one to Bob. The email body uses Handlebars to extract the name from the data file.

function(params) {  
    let result = this.callWorkerMethod("email", "sendmail", {    
        "to": [{      
            "address": {        
                "path": "email"      
            }    
        }],
        "subject": {      
            "text": "A Test Email"    
        },
        "body": {      
            "html": "<p>Hello {{name}}</p><p>This is a test email</p>"    
        },
        "data": {      
            "src": {        
                "refType": "URL",
                "ref": "http://timssite/media/examplejsonaddresses.json"      
            },
            "root": {        
                "path": "$.addressData"      
            }    
        }  
    });  
    return result;
}

Attachments

Attachments are added using FileReference objects. This example attaches a single item from the iCM media library to a plain text email.

function(params) {
    let result = this.callWorkerMethod("email", "sendmail", {
        "to": [{
            "address": params.to
        }],
        "subject": {
            "text": params.subject
        },
        "body": {
            "text": params.body
        },
        "attachments": [{
            "refType": "MEDIA",
            "ref": "1004|Thumbnail"
        }]
    });
    return result;
}

PDFs

The Email worker can compile data passed to it into a PDF that will be attached to an email. In the exmaple below note the use of style='page-break-before: always' to create page breaks in the PDF. Styling is supplied by the pdfboilerplate set in the worker.conf.

function(params) {
    let result = this.callWorkerMethod("email", "sendmail", {
        "to": [{
            "address": params.to
        }],
        "subject": {
            "text": params.subject
        },
        "body": {
            "text": params.body
        },
        "attachments": [{
            "refType": "MEDIA",
            "ref": "1004|Thumbnail"
        }, {
            "refType": "PDF",
            "ref": "<h1>Information about California</h1> <table style='border: solid 1pt; page-break-after: always' cellspacing='0'> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Name:</td> <td style='width:240.5pt;border: solid 0.5pt;' colspan='2'>CALIFORNIA</td> <td style='width:114pt;border: solid 0.5pt;'>Abbreviation:</td> <td style='width:37pt;border: solid 0.5pt;'>CA</td> </tr> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Capital:</td> <td style='width:128pt;border: solid 0.5pt;'>Sacramento</td> <td style='width:113pt;border: solid 0.5pt;'>Most populous city:</td> <td style='width:150.5pt;border: solid 0.5pt;' colspan='2'>Los Angeles</td> </tr> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Population:</td> <td style='width:128pt;border: solid 0.5pt;'>36,961,664</td> <td style='width:113pt;border: solid 0.5pt;'>Square miles:</td> <td style='width:150.5pt;border: solid 0.5pt;' colspan='2'>163,707</td> </tr> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Timezones:</td> <td style='width:128pt;border: solid 0.5pt;'>PT (UTC-8)</td> <td style='width:113pt;border: solid 0.5pt;'>&nbsp;</td> <td style='width:114pt;border: solid 0.5pt;'>Daylight Savings:</td> <td style='width:37pt;border: solid 0.5pt;'>YES</td> </tr>  </table><h1>Information about New York</h1> <table style='border: solid 1pt;' cellspacing='0'> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Name:</td> <td style='width:240.5pt;border: solid 0.5pt;' colspan='2'>NEW YORK</td> <td style='width:114pt;border: solid 0.5pt;'>Abbreviation:</td> <td style='width:37pt;border: solid 0.5pt;'>NY</td> </tr> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Capital:</td> <td style='width:128pt;border: solid 0.5pt;'>Albany</td> <td style='width:113pt;border: solid 0.5pt;'>Most populous city:</td> <td style='width:150.5pt;border: solid 0.5pt;' colspan='2'>New York</td> </tr> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Population:</td> <td style='width:128pt;border: solid 0.5pt;'>19,541,453</td> <td style='width:113pt;border: solid 0.5pt;'>Square miles:</td> <td style='width:150.5pt;border: solid 0.5pt;' colspan='2'>54,475</td> </tr> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Timezones:</td> <td style='width:128pt;border: solid 0.5pt;'>EST (UTC-5)</td> <td style='width:113pt;border: solid 0.5pt;'>&nbsp;</td> <td style='width:114pt;border: solid 0.5pt;'>Daylight Savings:</td> <td style='width:37pt;border: solid 0.5pt;'>YES</td> </tr> </table>  <h1 style='page-break-before: always'>Information about Massachusetts</h1> <table style='border: solid 1pt;' cellspacing='0'> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Name:</td> <td style='width:240.5pt;border: solid 0.5pt;' colspan='2'>MASSACHUSETTS</td> <td style='width:114pt;border: solid 0.5pt;'>Abbreviation:</td> <td style='width:37pt;border: solid 0.5pt;'>MA</td> </tr> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Capital:</td> <td style='width:128pt;border: solid 0.5pt;'>Boston</td> <td style='width:113pt;border: solid 0.5pt;'>Most populous city:</td> <td style='width:150.5pt;border: solid 0.5pt;' colspan='2'>Boston</td> </tr> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Population:</td> <td style='width:128pt;border: solid 0.5pt;'>6,593,587</td> <td style='width:113pt;border: solid 0.5pt;'>Square miles:</td> <td style='width:150.5pt;border: solid 0.5pt;' colspan='2'>10,555</td> </tr> <tr style='height:14pt'> <td style='width:69pt;border: solid 0.5pt;'>Timezones:</td> <td style='width:128pt;border: solid 0.5pt;'>EST (UTC-5)</td> <td style='width:113pt;border: solid 0.5pt;'>&nbsp;</td> <td style='width:114pt;border: solid 0.5pt;'>Daylight Savings:</td> <td style='width:37pt;border: solid 0.5pt;'>YES</td> </tr> </table>",
            "name": "theattachment.pdf"    
        }]
    });
    return result;
}

Last modified on 7 October 2024

Share this page

Facebook icon Twitter icon email icon

Print

print icon