Send Emails with Templates API¶

Method:¶

POST

Endpoint URL¶

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

https://xxxx.backendless.app/api/emailtemplate/send

Request headers¶

Content-Type: application/json  
user-token: optional value obtained as a result of the login operation.

where:

Argument Description

Content-Type Must be set to application/json. This header is mandatory.

user-token Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-token is set in the request, the currently logged in user will be assigned to the ownerId property of the user object which is being saved. Additionally, the operation will be executed with the security policy associated currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Request body¶

{  
  "template-name" : "value",  
  "addresses" : [ string values separated by comma ],  
  "cc-addresses" : [ string values separated by comma ],   
  "bcc-addresses" : [ string values separated by comma ],  
  "criteria" : "value",  
  "uniqueEmails": true | false,  
  "template-values" : {}  
  "attachment": [ string values separated by comma ]  
}

where:

Argument	Description
`template-name`	Name of an email template created in Backendless Console.
`addresses`	An array of email addresses to deliver an email generated from the template to. These email addresses are ignored if and when the `criteria` parameter is present.
`cc-addresses`	An array of email addresses to include into the CC (carbon copy) distribution list of the email message generated from the template.
`bcc-addresses`	An array of email addresses to include into the BCC (blind carbon copy) distribution list of the email message generated from the template.
`criteria`	A where clause for the `Users` table which defined the condition for selecting the users who will be receiving an email message generated from the template. The resulting collection of users takes precedence of the the email addresses (if any are) provided through the `addresses`argument.
`uniqueEmails`	A boolean value indicating whether a set of users identified by `criteria` should exclude any duplicates based on the `email` column value. If `criteria` returns multiple user records and some of them have the same email address, the server will send out multiple emails to the same address when `uniqueEmails` is set to `false` or only one email per user when the `uniqueEmails` value is set to `true`. Default value is `true`.
`template-values`	A JSON object containing values which will be used for Smart and Dynamic text substitutions. The property names in the object are matched against the Smart/Dynamic text placeholder names. The corresponding values are used for substitution in the resulting email message. Values must be of any primitive type.
`attachment`	An array of string values representing paths to the files stored in the Backendless Cloud. Specified files are attached to the email message. The path begins from the root of the Backendless Cloud without the leading slash. For instance, if the file `agreement.txt` is located at `/documents/legal/agreement.txt`, then the path passed to the parameter must be `documents/legal/agreement.txt`.

Example¶

Important

Make sure to replace xxxx in the domain name in the sample requests below to the one assigned to your application.

The example below sends out an email based on a template called "Marketing Template" to all users registered in the app whose email address does not end with @gmail.com and the related country is USA:

curl \  
-H Content-Type:application/json \   
-X POST \  
-d '{ \  
      "template-name" : "Marketing Template", \  
      "criteria": "email not like '%@gmail.com and address.country = 'USA'"\  
    }' \  
https://xxxx.backendless.app/api/emailtemplate/send

The example below sends out an email based on a template called "Marketing Template" to the users specified in the "addresses" field. The example demonstrates the usage of the "template-values" and the "attachment" fields. The "template-values"parameter contains two substitution values for the "Users.address.country" and the "discount" placeholders, and the "attachment" contains a path to the coupon20.png file.

curl \  
-H Content-Type:application/json \   
-X POST \  
-d '{ \  
      "template-name" : "Marketing Template", \  
      "addresses" : [ "joe@yahoo.com", "bob@hotmail.com" ], \  
      "template-values" : { \  
         "Users.address.country" : "your country", \  
         "discount" : "20% off",  
      }, \  
      "attachment" : ["marketing_files/discounts/coupon20.png"]  
    }' \  
https://xxxx.backendless.app/api/emailtemplate/send

Codeless Reference¶

email_api_send_email_template_1

where:

Argument	Description
`name`	Name of an email template created in Backendless Console.
`addresses`	A list of email addresses to deliver an email generated from the template to.
`query`	A where clause for the `Users` table which defined the condition for selecting the users who will be receiving an email message generated from the template. The resulting collection of users takes precedence of the the email addresses (if any are) provided through the `address` property.
`cc`	A list of email addresses to include into the CC (carbon copy) distribution list of the email message generated from the template.
`bcc`	A list of email addresses to include into the BCC (blind carbon copy) distribution list of the email message generated from the template.
`template values`	An object containing values which will be used for Smart and Dynamic text substitutions. The key names in the object are matched against the Smart/Dynamic text placeholder names. The corresponding values are used for substitution in the resulting email message. Values must be of any primitive type.
`attachments`	A list of string values representing paths to the files stored in the Backendless Cloud. Specified files are attached to the email message. The path begins from the root of the Backendless Cloud without the leading slash. For instance, if the file `agreement.txt` is located at `/documents/legal/agreement.txt`, then the path passed to the parameter must be `/documents/legal/agreement.txt`.
`unique emails`	A boolean value indicating whether a set of users identified by `query` should exclude any duplicates based on the `email` column value. If `query` returns multiple user records and some of them have the same email address, the server will send out multiple emails to the same address when `uniqueEmails` is set to `false` or only one email per user when the `uniqueEmails` value is set to `true`. Default value is `false`.
`return result`	When this box is checked, the operation returns an object containing the status of the email delivery or an error.

Returns an object containing the status of the email delivery or an error.

Consider the following records stored in the Users data table:

email_api_send_email_template_2

The example below sends an email message to the emails specified in the addresses property. Furthermore, the query property condition is set to include all users to the email delivery stored in the Users data table whose age is less than 30.

The template values property contains an object with the product_update_# property, representing the Smart Text. This property contains the value "Product Update #23" that replaces the Smart Text when the email is sent out.

Files that must be included to the email are specified in the attachments property as a list of paths leading to the corresponding files.

email_api_send_email_template_3