Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Getting Started with Email Notifications

Getting Started with Email Notifications

This article is not about the email functionality of User Management which uses predefined templates. However, some of the information presented here is applicable to it, such as how to edit the template.

Using the Email Notifications feature in Telerik Platform you can send automated email messages to users of your app based on templates.

Consider these examples:

  • You have a monthly email bulletin that you send to subscribers
  • You want to let your users know about an exciting offer
  • You need to notify your users about an upcoming outage in a service that you are offering through your app

In this tutorial you will learn how to create an email template featuring dynamically populated content and how to send emails based on it.

Steps at a glance:

Prerequisites

Create an Email Template

The Email Notifications feature in Telerik Platform requires you to create an email template before basing an email message on it.

Templates provide the benefit of reusing your messages, dynamically populating them with event-specific data as you go.

To create an email template:

  1. Log in to the Telerik Platform portal.
  2. Click your app.
  3. Navigate to Notifications > Email Notifications > Templates.
  4. Click the Add an email template button.

    You will see the Create an email template form.

Fill In the Template Form

You have two options filling in the template form: providing fixed data or inserting placeholders. Placeholders allow you to set the field value later, when sending the email message.

These are the fields you can modify:

  • Name—A name that you use to identify the email template in the UI and to refer to it in your code. Cannot contain blank characters. Example: "NotifyAdminTemplate".
  • Subject—The subject line that the email recipient will see.
  • From email—The sender's email address that the email recipient will see.
  • From name—The sender's name.
  • Reply to—The email address that the recipient should use for sending replies.
  • CC—A list of email addresses that are to receive a carbon copy of the email.
  • BCC—A list of email addresses that are to receive a blind carbon copy of the email.
  • Message—The body of the email message.

You can use placeholders to dynamically set the data in any field except for the Name field. There are two types of placeholders that you can use:

System placeholders

System placeholders are populated with built-in variables that you can manage on Emails → Settings (or if you have added the User Management service, you can also use Users → Email Settings to set the same values).

  • {{DefaultFromEmail}}
  • {{DefaultFromName}}
  • {{DefaultReplyToEmail}}

Custom placeholders

In addition to system placeholders, you can define an arbitrary number of your own placeholders.

To create and use a custom placeholder, take these steps:

  1. Insert a placeholder in a field of your choosing using the following format:

    {{YourPlaceholderName}}

  2. Set the placeholder value in the context parameter of your payload (see next step).

Examples include:

  • {{NotificationSubject}}
  • {{MessageBody}}

An example of a populated template form is shown on the figure below:

A sample email template.

Click Save when you are ready.

Use the Design view of the template editor to configure the template with the options available in the editor or the HTML view to add your custom HTML markup and CSS styles. Adding placeholders is supported in both views.

Set Up the Template Parameters

After you have created the template, you can refer to it by name in your code to send email notifications. But first you need to set its parameters. You typically do this in a JSON-formatted payload to a RESTful call or by setting variables in your code. These are the parameters you need to set:

  • templateName—the unique name you gave to the template at the time of creating it
  • recipients—an array of email addresses which you intend to send the email to
  • context—an object containing key-value pairs that binds placeholder names to actual values that you want to use in the email

The following example shows a JSON object that sets the values for the example template from the previous step.

{
  "TemplateName": "NotifyAdminTemplate",
  "Recipients": ["your-email@youremailserver.com"],
  "Context": {
    "NotificationSubject": "New items require your attention",
    "MessageBody": "You have new items for approval."
  }
}

Don't forget to enter the actual recipient addresses in the Recipients array prior to using the payload.

Declare a Cloud Function that Sends Email Notifications

By creating a cloud function that sends an email from your template you define a RESTful endpoint that you can access whenever you need to notify your users about something. (Find out how to create a cloud function in Implementing Cloud Functions.)

The following code snippet provides example code that you can include in your cloud function to send an email notification based on a payload like the one from the previous step:

Everlive.CloudFunction.onRequest(function(request, response, done) {
    if (request.action === 'POST') {

        var templateName = request.data.TemplateName;
        var recipients = request.data.Recipients;
        var context = request.data.Context;

        Everlive.Email.sendEmailFromTemplate(templateName, recipients, context, function(err, res) {
            if (err) {
                response.body = err;
                done();
            } else {
                response.body = res;
                done();
            }
        });

    } else {
        response.body = {
            "Response": "Please make a POST request and provide the required parameters."
        };
        response.statusCode = 404;
        done();
    }
});

You can also send Email notifications using the Backend Services RESTful API. See RESTful API: Sending Email Programmatically for more information.

Execute the Cloud Function

  1. Click Execute.
  2. In the window that appears, choose the POST verb and pass the object that sets the template variables as request body.

Sending an email notification from a cloud function

Evaluate the Response

The cloud function that sends the email notification is set to return the full execution result. It contains the HTTP response code among other details.

Example:

{
    "statusCode": 200,
    "body": "{\"Result\":null}",
    "headers": {
        "server": "nginx",
        "date": "Mon, 30 Mar 2015 10:56:57 GMT",
        "content-type": "application/json; charset=utf-8",
        "content-length": "15",
        "connection": "keep-alive",
        "x-powered-by": "Everlive",
        "access-control-allow-credentials": "true"
    },
    "data": {
        "Result": null
    }
}

If you want to, you can change the code to return only a part of the full response or to return a custom response.

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.