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
| Name | Type | Description |
|---|---|---|
| to | Array, required | An array of address objects |
| cc | Array, optional | An array of address objects |
| bcc | Array, optional | An array of address objects |
| from | Object, optional | A single address object. If not set will use the address from the worker.conf |
| replyTo | Array, optional | An array of address objects |
| subject | Object, required | An object with the following properties |
| subject.text | String, required | The email subject. Can be a simple string or Handlebars template |
| subject.useHandlebars | Boolean, optional | If |
| body | Object, required | Either text or html must be supplied |
| body.text | String, optional | The email body. Can be a simple string or Handlebars template |
| body.html | String, optional | The email body. Can be a simple string or Handlebars template |
| body.useHandlebars | Boolean, optional | If |
| body.analytics | Object, optional | Add Google Analytics tracking to email |
| attachments | Array, optional | An array of FileReference objects |
| data | Object, optional | Required if using JSONPath objects in your address objects or if using Handlebars in subject or body |
| data.src | Object or string, required if using a data object | Either a FileReference object or string of iCM Bulk Mail rule IDs |
| data.root | Object, required if using a data object | A JSONPath object |
| data.root.path | String, required if using a data object | The path to the root of the data. This should return a single object or an array. An email will be sent to each |
| data.csv | Object, optional | Additional processing if the |
| data.csv.skip | Integer, optional | Rows to skip at the top of the file. Default 0 |
| data.csv.header | Boolean, optional | Does the first row contain header names? Default false. If true the resulting JSON can be accessed as col0, col1, col2 etc |
| data.csv.sep | String, optional | A custom separator. Defaults to |
| data.csv.quote | String, optional | A custom quote character. Defaults to |
| helpers | Object, optional | A FileReference object containing Handlebars helper definitions |
| SMTPServer | String, optional | Will use the value from worker.conf if not set |
| SMTPPort | Integer, optional | Will use the value from worker.conf if it exists |
| SMTPAuth | Boolean, optional | Will use the value from worker.conf if it exists |
| SMTPTLS_SSL | String, optional | Will use the value from worker.conf if it exists |
| SMTPUser | String, optional | Will use the value from worker.conf if it exists |
| SMTPPassword | String, optional | Will use the value from worker.conf if it exists |
| bounceTo | String, optional | Will 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
| Property | Type | Description |
|---|---|---|
| messages | String | Any error messages |
| failed | Integer | The number of failed emails |
| sent | Integer | The 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 -
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
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
{
"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
Note that
{
"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"
}
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
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
| Name | Type | Description |
|---|---|---|
| analytics | Object | An object with the following properties |
| analytics.tid | String, required | The tracking ID. Use the tracking ID of your site |
| analytics.cid | String, optional | A client ID. If missing a random UUID will be supplied |
| analytics.uid | String, optional | A user ID string or JSONPath object representing a unique ID for each email |
| analytics.dp | String, optional | Google recommend using /email/ |
| analytics.campaign | Object, optional | Provides campaign tracking, made up of the following properties |
| analytics.campaign.cs | String | The campaign source |
| analytics.campaign.cm | String | The campaign medium |
| analytics.campaign.cn | String | The campaign name |
| analytics.campaign.metrics | Array | An array of custom metrics (strings) |
| analytics.campaign.addToLinks | String | Any 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
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
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;'> </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;'> </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;'> </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;
}
Share this page
