Skip to content

Send Emails with Templates API

Method:

POST


URL

https://api.backendless.com/<app-id>/<REST-api-key>/emailtemplate/send

where:

Argument                Description
<application-id> the ID of your application generated upon its creation. You can get the value in the Manage > App Settings section of the Backendless Console.
<REST-api-key> REST API key of your application. You can get the value from the Manage > App Settings section of the Backendless Console.

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",  
  "template-values" : {}  
}

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 addressesargument.
template-values A JSON object containing values which will be used 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.

Example

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://api.backendless.com/XXXXX-XXXXX-XXXXX/ZZZZZ-ZZZZZ-ZZZZZ/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" field. It contains two substitution values for the "Users.address.country" and the "discount" placeholders:

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"  
      } \  
    }' \  
https://api.backendless.com/XXXXX-XXXXX-XXXXX/ZZZZZ-ZZZZZ-ZZZZZ/emailtemplate/send