Skip to content

Send Emails with Templates API

The API for sending email for a template relies on a special entity called EmailEnvelope. This entity contains information about the email recipients. Specifically:

  • a list of email addresses for the "To", "Cc" and "Bcc" fields of the email message
  • a query, also known as a where clause, against the Users database table, which identifies the recipients of the email. The query takes precedence and overrides the email addresses for the "To" field.

The EmailEnvelope class is defined as:

public class EmailEnvelope {
   private String query;
   private Set<String> to;
   private Set<String> cc;
   private Set<String> bcc;
   private boolean uniqueEmails = true;

   // set a query (where clause) to identify the users who will be receiving the email
   public void setQuery( String query );

   // adds an email address to what's already in the envelope
   public void addTo( String email );

   // adds a collection of addresses to what's already in the envelope
   public void addTo( Set<String> emails );

   // removes the existing "to" collection and sets the provided one
   public void setTo( Set<String> emails );

   public void addCc( String email );
   public void addCc( Set<String> emails );
   public void setCc( Set<String> emails );

   public void addBcc( String email );
   public void addBcc( Set<String> emails );
   public void setBcc( Set<String> emails );

   public void setUniqueEmails( boolean uniqueEmails );
}

where:

Argument                Description
to An array of email addresses to deliver an email generated from the template to. These email addresses are ignored if and when the query parameter is present.
cc An array of email addresses to include into the CC (carbon copy) distribution list of the email message generated from the template.
bcc An array of email addresses to include into the BCC (blind carbon copy) distribution list of the email message generated from the template.
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 to property.
uniqueEmails A boolean value indicating whether a set of users identified by query should exclude any duplicates based on the email column value. If queryreturns 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.

Non-Blocking API

public void sendEmailFromTemplate( String templateName, 
                                   EmailEnvelope envelope, List<String> attachments, 
                                   AsyncCallback<MessageStatus> responder )

public void sendEmailFromTemplate( String templateName, 
                                   EmailEnvelope envelope, 
                                   Map<String, String> templateValues, List<String> attachments, 
                                   AsyncCallback<MessageStatus> responder )
public void sendEmailFromTemplate( String templateName, 
                                  EmailEnvelope envelope, 
                                  AsyncCallback<MessageStatus> responder )

public void sendEmailFromTemplate( String templateName, 
                                   EmailEnvelope envelope, 
                                   Map<String, String> templateValues, 
                                   AsyncCallback<MessageStatus> responder )

Blocking API

public sendEmailFromTemplate( String templateName, 
                              EmailEnvelope envelope, List<String> attachments )

public sendEmailFromTemplate( String templateName, 
                              EmailEnvelope envelope, 
                              Map<String, String> templateValues, List<String> attachments )
public sendEmailFromTemplate( String templateName, 
                              EmailEnvelope envelope )

public sendEmailFromTemplate( String templateName, 
                              EmailEnvelope envelope, 
                              Map<String, String> templateValues )

where:

Argument                Description
templateName Name of an email template created in Backendless Console.
envelope An instance of the EmailEnvelope class containing information about the email recipients.
templateValues 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.
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

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:

EmailEnvelope envelope = new EmailEnvelope();
envelope.setQuery("email not like '%@gmail.com' and address.country = 'USA'");

Backendless.Messaging.sendEmailFromTemplate("Marketing Template", envelope, new AsyncCallback<MessageStatus>() {
   @Override
   public void handleResponse(MessageStatus response) {
       Log.i(TAG, "Email has been sent");
   }

   @Override
   public void handleFault(BackendlessFault fault) {
       Log.e(TAG, fault.getMessage());
   }
});
val envelope = EmailEnvelope()
envelope.query = "email not like '%@gmail.com' and address.country = 'USA'"

Backendless.Messaging.sendEmailFromTemplate("Marketing Template", envelope,
   object : AsyncCallback<MessageStatus> {
       override fun handleResponse(response: MessageStatus) {
           Log.i(TAG, "Email has been sent")
       }

       override fun handleFault(fault: BackendlessFault) {
           Log.e(TAG, fault.message)
       }
   })

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

Set<String> addresses = new HashSet<>();
addresses.add("joe@yahoo.com");
addresses.add("bob@hotmail.com");

Map<String, String> templateValues = new HashMap<>();
templateValues.put("Users.address.country", "your country");
templateValues.put("discount", "20% off");

EmailEnvelope envelope = new EmailEnvelope();
envelope.setTo(addresses);

List<String> attachment = new ArrayList<>();
attachment.add("marketing_files/discounts/coupon20.png");

Backendless.Messaging.sendEmailFromTemplate("Marketing Template", envelope, templateValues, attachment, new AsyncCallback<MessageStatus>() {
   @Override
   public void handleResponse(MessageStatus response) {
       Log.i(TAG, "Email has been sent");
   }

   @Override
   public void handleFault(BackendlessFault fault) {
       Log.e(TAG, fault.getMessage());
   }
});
val addresses = setOf("joe@yahoo.com", "bob@hotmail.com")

val templateValues = mapOf("Users.address.country" to "your country", "discount" to "20% off")

val envelope = EmailEnvelope()
envelope.to = addresses

Backendless.Messaging.sendEmailFromTemplate("Marketing Template", envelope, templateValues,
   object : AsyncCallback<MessageStatus> {
       override fun handleResponse(response: MessageStatus) {
           Log.i(TAG, "Email has been sent")
       }

       override fun handleFault(fault: BackendlessFault) {
           Log.e(TAG, fault.message)
       }
   })

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