Send Email

ID: sendEmail

Sends an email to a recipient. To send an email using this action, it is required that you identify:

  1. The email provider to be used to send the email (applicationId and emailProviderId
  2. The recipient of the email (using to or toPrincipalId)
  3. Who the email is from (either using from or the default from value of your email provider)
  4. The body of the email (by either specifying body directly, via a node reference or via an Email Template reference)
  5. The subject of the email

All other properties are optional.

Configuration

Here is a full breakdown of the configuration properties:

The Email Provider

In order to send emails, you first have to identify the Email Provider to be used in sending any emails. An Email Provider is configured on an application basis. Thus, different mobile or web or tenant applications can have entirely different email configurations (this can be very useful and enables you to redeploy email templates quickly from one project to the next).

Property Type Required Description
applicationId text true The ID of the application data store that holds the reference to the email provider.
emailProviderId text true The ID of the email provider.

The Recipient

You specify who receives the email either by plugging in an email address for the to field or by supplying the toPrincipalId (principal ID) of the Domain User receiving the email. The email address of the recipient will be used automatically.

Property Type Required Description
to text true The email address of the email recipient
toPrincipalId text false As an alternative to the to field, allows you to specify the principal ID of the domain user to receive the email. The email field will be used from the domain user to determine the recipient address.

Who it is From

There are two ways to specify who the email is from. If you've set the from field on the email provider, then this will be used automatically. In which case, you don't need to do anything else. In many cases, a single email provider will have a common and consistent from address. Thus, this helps so that you don't need to fill it in over and over again.

That said, if you want to specify the from address each time, you do so by just plugging it in.

Property Type Required Description
from text true The email address of the email sender. If an email provider is being used, the *from* property of the email provider will be used if nothing is provided here.

The Body of the Email

The body of the email is required. There are three ways to specify it:

  • With a straight up text string in the body property.
  • By referencing a node's attachment.
  • By referencing an email template.

Here are the properties:

Property Type Required Description
body text false The body of the email. (Method #1)
bodyRepositoryId text false The ID of the repository containing the node whose attachment contains the body of the email (Method #2).
bodyBranchId text false The ID of the branch containing the node whose attachment contains the body of the email (Method #2).
bodyNodeId text false The ID of the node whose attachment contains the body of the email (Method #2).
bodyAttachmentId text false The attachment ID on the node that holds the body of the email (Method #2).
templateRepositoryId text false The ID of the repository containing the email template (Method #3).
templateBranchId text false The ID of the branch containing the email template (Method #3).
templateKey text false The key of the email template (Method #3).

The Subject and Optional Properties

The only other required property is the subject. Everything else is optional as per listed here:

Property Type Required Description
subject text true The subject of the email.
cc text false A comma-delimited carbon copy (CC) list of recipient email addresses.
bcc text false A comma-delimited blind carbon copy (BCC) list of recipient email addresses.
replyTo text false The email address to serve as a reply to address.
repositoryId text false The ID of the repository containing a node (which binds into the model as node).
branchId text false The ID of the branch containing a node (which binds into the model as node).
nodeId text false The ID of the node (which binds into the model as node).

Template Model

You may provide a model to populate any root-scoped variables for use in your templates. The model is an object consisting of key/value pairs.

Property Type Required Description
model object false Key/value pairs that serve as root-scoped variables during template execution.

If a model isn't provided, an empty model is assumed.

The model will automatically be populated with the following additional variables:

  • node - the current content node
  • branch - the current branch
  • repository - the current repository
  • user - the current user

Examples

For the examples below, let's imagine that we have an Press Release content type that looks like this:

{
    "_qname": "my:press-release",
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        },
        "subject": {
            "type": "string"
        },
        "body": {
            "type": "string"
        },
        "links": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "title": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string"
                    },
                    "altText": {
                        "type": "string"
                    }
                }
            }
        }
    }
}

Let's also assume that we have the following content item:

{
    "_type": "my:press-release",
    "title": "Party Invitation",
    "subject": "You are invited to a Party!",
    "body": "Mr. Bilbo Baggins of Bag End has announced that will shortly be celebrating his eleventy-first birthday with a party of special magnificence.  There has been much talk of it and excitement in Hobbiton!  Bilbo is very rich and very peculiar, and has been the wonder of the Shire for sixty years, ever since his remarkable disappearance and unexpected return.",
    "links": [{
        "title": "About the Shire",
        "url": "https://en.wikipedia.org/wiki/The_Shire",
        "altText": "About the Shire"
    }, {
        "title": "Visit the Shire",
        "url": "https://www.newzealand.com/us/waikato/",
        "altText": "Visit the Shire "
    }, {
        "title": "Sounds of the Shire",
        "url": "https://www.youtube.com/watch?v=LML6SoNE7xE",
        "altText": "Sounds of the Shire"
    }]
}

Using Configuration

Let's send an email using direct configuration of the sendEmail action.

{
    "to": "frodo@shire.com",
    "subject": "{{node.properties.subject}}",
    "body": "<p>{{node.properties.body}}</p><ul>{{#each node.properties.links}}<li><a title="{{altText}}" href="{{url}}">{{title}}</a></li>{{/each}}</ul>"
}

This will send an email to frodo@shire.com using the default Email Provider for your platform. The default Email Provider must have a from address specified on it. If it doesn't (or if you wish to change the from header for your email), you will need to provide it, like this:

{
    "to": "frodo@shire.com",
    "from": "gandalf@middle-earth.com",
    "subject": "{{node.properties.subject}}",
    "body": "<p>{{node.properties.body}}</p><ul>{{#each node.properties.links}}<li><a title="{{altText}}" href="{{url}}">{{title}}</a></li>{{/each}}</ul>"
}

If you want to use a different Email Provider instance, you will need to create one (within an Application) and then additionally provide the following:

  • applicationId
  • emailProviderId

The keys for the sendEmail action configuration are processed through a template processor. The template processor is detected based on the markup in your values. The following template processors are supported:

  • Handlebars (text/x-handlebars-template))
  • Freemarker (application/freemarker)

In this example, we use Handlebars. We use Handlebars for the subject and body properties. The body property, when expanded, looks like this:

<p>
    {{node.properties.body}}
</p>
<ul>
    {{#each node.properties.links}}
    <li>
        <a title="{{altText}}" href="{{url}}">
            {{title}}
        </a>
    </li>
    {{/each}}
</ul>

If we wanted to use FreeMarker, we could write the same thing like this:

<p>
    ${node.properties.body}
</p>
<ul>
    <#list node.properties.links as link>
    <li>
        <a title="${link.altText}" href="${link.url}">
            ${link.title}
        </a>
    </li>
</#list>
</ul>

The resulting email will have the subject You are invited to a Party!.

And the body of the email will be:

<p>
    Mr. Bilbo Baggins of Bag End has announced that will shortly be celebrating his eleventy-first birthday with a party of special magnificence.  There has been much talk of it and excitement in Hobbiton!  Bilbo is very rich and very peculiar, and has been the wonder of the Shire for sixty years, ever since his remarkable disappearance and unexpected return.
</p>
<ul>
    <li>
        <a title="About the Shire" href="https://en.wikipedia.org/wiki/The_Shire">
            About the Shire
        </a>
    </li>
    <li>
        <a title="Visit the Shire" href="https://www.newzealand.com/us/waikato/">
            Visit the Shire
        </a>
    </li>
    <li>
        <a title="Sounds of the Shire" href="https://www.youtube.com/watch?v=LML6SoNE7xE">
            Sounds of the Shire
        </a>
    </li>
</#list>
</ul>

Using an Node Attachment

If you're doing anything interesting, your email body templates will get a bit lengthy. Which can be tedious to edit or work with.

Fortunately, Cloud CMS lets you write your templates as content nodes and then reference them. That way, your developers or editorial teams can make simple changes to text documents and have that text get used automatically as a template for any emails that are sent.

To support this, all we need to do is create a piece of content that has a text attachment with a mimetype that is compatible for one of the supported template processors. Your text attachment should be one of the following types:

  • text/x-handlebars-template
  • application/handlebars

Suppose we have an attachment named template of type text/x-handlebars-template with the following text:

<p>
    {{node.properties.body}}
</p>
<ul>
    {{#each node.properties.links}}
    <li>
        <a title="${altText}" href="${uri}">
            ${title}
        </a>
    </li>
    {{/each}}
</ul>

We can now configure our sendEmail action like this:

{
    "to": "frodo@shire.com",
    "subject": "{{node.properties.subject}}",
    "bodyNodeId": "<templateNodeId>",
    "bodyAttachmentId": "template"  
}

Where bodyNodeId is the ID of the node that contains our template and bodyAttachmentId is the name the attachmnent on that node that holds our template. If bodyAttachmentId isn't provided, the attachment ID of default will be used.

Using an Email Template

An even easier way to work with templates is to create an Email Template (n:email_template). You can create this by hand or you can create one using the Email Templates page within the user interface.

Give your Email Template a key. For example, let's imagine we create an Email Template with the key of email1.

{
    "_type": "n:email_template",
    "title": "My First Email Template",
    "key": "email1"
}

The Email Template has a default attachment that looks like this:

<p>
    {{node.properties.body}}
</p>
<ul>
    {{#each node.properties.links}}
    <li>
        <a title="${altText}" href="${uri}">
            ${title}
        </a>
    </li>
    {{/each}}
</ul>

We can now configure our sendEmail action like this:

{
    "to": "frodo@shire.com",
    "subject": "{{node.properties.subject}}",
    "key": "email1"
}

That's all there is to it.