--- title: "Send Email" description: "Optimize sending emails with our detailed guide, including provider setup, recipient options, and template configuration. (Gitana 4.0)" product: "Gitana" version: "4.0" url: "/documentation/gitana/4.0/engine/behaviors/actions/send-email" --- # 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](/documentation/gitana/4.0/reference/types/emailProvider.md) to be used in sending any emails. An [Email Provider](/documentation/gitana/4.0/reference/types/emailProvider.md) is configured on an [application](/documentation/gitana/4.0/reference/types/application.md) 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](/documentation/gitana/4.0/reference/types/emailProvider.md), 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 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 a 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": "

{{node.properties.body}}

" } ``` 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": "

{{node.properties.body}}

" } ``` 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](https://handlebarsjs.com/ "Handlebars"). We use Handlebars for the `subject` and `body` properties. The `body` property, when expanded, looks like this: ```

{{node.properties.body}}

``` If we wanted to use [FreeMarker](https://freemarker.apache.org/ "FreeMarker"), we could write the same thing like this: ```

${node.properties.body}

``` The resulting email will have the subject `You are invited to a Party!`. And the body of the email will be: ```

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.

``` ### Using a 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: ```

{{node.properties.body}}

``` We can now configure our `sendEmail` action like this: ``` { "to": "frodo@shire.com", "subject": "{{node.properties.subject}}", "bodyNodeId": "", "bodyAttachmentId": "template" } ``` Where `bodyNodeId` is the ID of the node that contains our template and `bodyAttachmentId` is the name the attachment 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: ```

{{node.properties.body}}

``` 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. ## See Also - The [Email](/documentation/gitana/4.0/engine/workflow/workflow-handlers/email.md) workflow handler