Custom Email Notifications

Ayla offers a white label service that allows OEMs to customize all end-user facing aspects of the system. This includes email notifications sent to end users by the Ayla Cloud on behalf of the OEM. To customize email notifications, OEMs use the Ayla Customer Dashboard to design an HTML email template. In the templates, OEMs can incorporate their company's logo and create reusable messages with dynamic content.

This is done on the Message Templates tab in the OEM Profile, as shown in the following example:

Currently, email templates are most often used for the following services:

Property triggers (when the trigger condition is set to True, an alert is sent)
User confirmation on sign-up (or re-confirmation of original email request)
User password reset instructions
Device sharing

The Customization Process

There are two options in the Ayla Customer Dashboard to customize email notifications:

Create a new email template by downloading a sample template from the Message Templates tab in the OEM Profile of the Ayla Customer Dashboard, as shown below:

Repurpose one of your existing email templates by downloading it from your email template list in the dashboard. To do this, you click the Download Template icon for the template you wish to modify, as shown in the following example:

Customizable Sample Templates

When creating a new email notification using the sample templates, you first add basic information about the template to identify it in the Ayla Platform. The template details are added to the table listing on the Message Templates tab.

This is done using the Create New Email Template dialog box, shown below. Click the ADD NEW button on the Message Template tab to open this dialog box.

When you enter the Unique ID, keep in mind that this is listed as the Template ID on the Message Template tab and is used in the web or mobile app as an API parameter. The Ayla Cloud uses the template ID when building and delivering the appropriate email template. For example, when an email is to be sent, the Ayla Cloud looks for the template based on the specified template ID and uses that template to build an email body after performing all the substitutions.

The sample templates are part of a zip file (ayla_custom_email_samples.zip). Once you click the DOWNLOAD SAMPLE button on the Message Template tab, the zip file downloads to your device and opens. In the zip file, there is a folder that contains zipped sample templates for different types of emails (based on common use cases). You can extract the zipped files to your preferred location. The zipped sample templates are:

example
password_reset
resource_share
signup_confirmation
trigger_app

Refer to the Examples of the Sample Templates section for more details and end-use examples of each sample template.

All of the sample templates include basic information found in emails. There are also sample HTML files and images (e.g., logos and mobile app icons). The HTML files can be edited in any text or HTML editor. You just need to maintain the formatting styles and image names. Refer to the Email Template Rules section for guidelines on modifying the downloaded files.

When you finish creating your new template, refer to the Uploading New Templates section to properly add your new template to the Ayla Platform.

Repurposing of Existing Templates

If you already have an email template that has similar content and formatting to your new intended end use, you can download, modify, and rename that template for its new purpose. As with the customizable sample templates, you first need to create a unique identification for the repurposed template to use it in the Ayla platform. This is done by clicking the Add New button (shown below) and completing the Create New Email Template dialog box as explained in the previous section, Customizable Sample Templates.

After creating an entry in the table listing on the Message Template tab for your new (repurposed) template, use the search tool to find the template that you wish to repurpose. Like the sample templates, all existing templates are zip files. Therefore, when you click the Download Template icon for the template you wish to repurpose, the zip file downloads to your device and opens. Refer to the following example:

If the following error message appears on the Message Templates tab, the template file is missing. It may not have been uploaded correctly. This template is therefore not being used in the Ayla Platform. You must find and upload this file if you are expecting that it is being used in the platform. See the Uploading New Templates section to make sure this is done correctly. Then you can repurpose this template per this section.

Uploading New Templates

You must properly format and upload the template file for use in the Ayla Platform. Whether created from a sample template or a repurposed existing template, carefully review the Email Template Rules section to make sure your new template meets the requirements. There are specific guidelines depending on your intended end use for the template (e.g., templates for user password reset instructions) as well.

After confirming that your new template is properly formatted, compress all of the files that make up the template (i.e., HTML, text, and images) into a zipped file.

IMPORTANT! Files sizes are restricted to 1MB; files larger than this size cannot be uploaded to the dashboard.

Then, locate the template entry in the list on the Message Template tab, using the search tool if needed. Click the Upload Template icon (as shown in the following example) to add your new template to the Ayla Platform.

When you click the Upload Template icon, a typical File Upload dialog box displays, in which you locate the compressed file and click Open to upload the file. If the file does not upload properly, the following message displays. This may occur, for example, if the security validation detects any ruby/javascript executable code in the template.

When the file uploads successfully, the following message displays:

Email Template Rules

Templates contain all of the HTML and style elements needed for the notification. Follow the naming rules and file structure explained in this section to ensure that the template is accepted by the Ayla Platform:

For HTML templates, the file name should be template.html.
With regard to images:
When creating templates for the following end uses, you need to create a separate text file for your email's subject line:
You no longer have to add the subject line to web or mobile app as an API parameter. See the subject line text file in the example of the compressed file below:

You should always compress the HTML , text, and image files into a zipped file. Refer to the example above. Files sizes are restricted to 1MB; files larger than this size cannot be uploaded to the dashboard.
No scripts are allowed as part of the HTML.
You must use tags to specify how and where situational data is inserted when the email is constructed on the Ayla Cloud. The following tags are supported for substitution:
All of the tags listed above can be categorized based on the origin of their substitutions. The categories are as follows:
Tags for the data that comes from the uploaded template:
Tags for the data that comes from the Ayla Cloud:
User sign-up (re) confirmation-related tags:
User password reset-related tags:
The double-bracketing format [[xxxx]] is important for proper substitutions.
A template for a trigger-alert email may display details similar to the following:
file://localhost/Users///ayla_custom_email_samples>/trigger_app/template.html
logo image
[[trigger_app_email_body]]
open your app here:
Following is an example of an email after the substitutions were made in the Ayla Cloud:

This sample email (above) was constructed using the trigger_app_email_body. This was passed as a parameter to the trigger_app. See the code below:

<tr>
<td valign="middle" class="td4">
<p class="p2"><br></p>
</td>
</tr>
<tr>
<td valign="middle" class="td4">
<h2 style="margin: 0.0px 0.0px 29.0px 0.0px; font: 36.0px Arial; color: #153643"><b>Hello [[username]]</b></h2>
</td>
</tr>
<tr>
<td valign="middle" class="td4">
<h2 style="margin: 0.0px 0.0px 29.0px 0.0px; font: 36.0px Arial; color: #153643"><b>[[property_name]]</b> is now <b>[[property_value]]</b> degrees on your [[device_product_name]].</h2>
</td>
</tr>

Managing Email Templates

You can manage your templates on the Message Templates tab of your OEM Profile in the Ayla Customer Dashboard.

If you wish to view or modify template details, locate the template entry in the table listing, using the search tool if needed. Click the template entry to modify the template details. Refer to the following example:

You can also delete the template from the Ayla Platform by clicking the trash can icon, as shown below:

To ensure that the template is removed from the platform, you must click ACCEPT in the confirmation message box that displays when you click the trash can icon.

Examples of the Sample Templates

Ayla's sample templates provide you with the basic contents of an email for a particular end use. As explained in the Customizable Sample Templates section, there is a zipped file for each sample template. This section has details and examples to reference when you are adapting the sample templates for your end use.

Example Sample Template

The Example zipped file contains a plain, simple formatted email. Do NOT use the template.html file. An email can only be sent if there is an API call for a unique email_template_id, which is not included in this template.html file. Below is an email example of this template.html file:

Password Reset Sample Template

The template in this folder enables you to respond to a Password Reset request (as shown in the example below). When modifying this template, you can create a separate text file for your email's subject line. You no longer have to add the subject line to web or mobile app as an API parameter.

Following are the fields that you can add to the Password Reset template to display the appropriate values for the parameters in the double brackets "[[ ]]":

[[logo_image]]
[[user_name]]
[[user_password_reset_token]]
[[ios_app_link_image]]
[[android_app_link_image]]

When using this template for user password resets, the Ayla User Service POST URL should include:

email_template_id (which is required) - unique ID of the template assigned to the email template when it was created.
email_subject (which is optional) - customer email subject line. As stated above, this no longer has to be added to the web or mobile app as an API parameter.
email_body_html (which is optional) - HTML coding with tags specific to this resend request app.

Refer to Ayla API Reference for an example of this API. Ayla API Reference is an interactive environment to learn and test all the APIs in the Ayla IoT Cloud.

Resource Share Sample Template

The template in this folder enables you to send out a shared link, as shown in the following example:

Following are the fields that you can add to the Resource Share template to display the appropriate values for the parameters in the double brackets "[[ ]]":

[[logo_image]]
[[share_target_user_name]]
[[share_owner_user_name]]
[[share_operation]]
[[share_resource_name]]
[[share_resource_id]]
[[ios_app_link_image]]
[[android_app_link_image]]

Signup Confirmation Sample Template

The template in this folder enables you to send a Sign-up Confirmation link (as shown in the example below). When modifying this template, you can create a separate text file for your email's subject line. You no longer have to add the subject line to web or mobile app as an API parameter.

Following are the fields that you can add to the Signup Confirmation template to display the appropriate values for the parameters in the double brackets "[[ ]]":

[[logo_image]]
[[user_name]]
[[user_confirmation_token]]
[[ios_app_link_image]]
[[android_app_link_image]]

When using this template for user signups, the Ayla User Service POST URL should include:

email_template_id (which is required) - unique ID of the template assigned to the email template when it was created.
email_subject (which is optional) - customer email subject line. As stated above, this no longer has to be added to the web or mobile app as an API parameter.
email_body_html (which is optional) - HTML coding with tags specific to this resend request app.

Refer to Ayla API Reference for an example of this API. Ayla API Reference is an interactive environment to learn and test all the APIs in the Ayla IoT Cloud.

Trigger App Sample Template

The trigger app email is used if you want the app to send an email when a specific datapoint property value becomes TRUE. The template is formatted as shown in the following example, which can be modified as needed:

In the template.html file, locate this tag: [[trigger_app_email_body]]. Create the following fields to be included in the POST to the Ayla Device Service (ADS):

email_template_id (which is required) - unique ID of the template assigned to the email template when it was created.
- email_subject (which is optional) - customer email subject line. As stated above, this no longer has to be added to the web or mobile app as an API parameter.
- email_body_html (which is optional) - HTML coding with tags specific to this resend request app.
  These fields are designed to help you customize your trigger app email for the device and device property that will trigger this email.
  As with the other email templates, you can you add appropriate values in each of the double brackets “[[ ]]”. Fields that can be added include:
- [[logo_image]]
- [[trigger_app_email_body]]
- [[ios_app_link_image]]
- [[android_app_link_image]]

Refer to Ayla API Reference for an example of this API. Ayla API Reference is an interactive environment to learn and test all the APIs in the Ayla IoT Cloud.

Launching Mobile Apps from the Email

To improve the end user's experience, you may want to embed a link in the email template, enabling the end user to launch the mobile app from the email client. This link should correspond to a custom URL scheme configured on the mobile device that will be launching the mobile app. For example:

aylaaura://aylapp?param1=value1

Some email clients (notably the Gmail app) strip the custom URL links, causing the app not to launch. The Ayla Cloud provides a URL that can be used to redirect to a custom URL scheme. For example:

https://app-launcher.aylanetworks.com/launch?custom_url=aylacontrol://aylaapp?param1=value1

Testing the Email Template

We recommend that you test your new template to make sure it is formatted and working properly and as you intended. Following are simple steps to do this:

Set a value for a property to generate the trigger and response.
Monitor the response and review the content and formatting.
If needed, modify the template. Refer to the Managing Email Template section.