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:

@interface EmailEnvelope : NSObject

@property (nonatomic, copy) NSArray<NSString *> * _Nullable to;
@property (nonatomic, copy) NSArray<NSString *> * _Nullable cc;
@property (nonatomic, copy) NSArray<NSString *> * _Nullable bcc;
@property (nonatomic, copy) NSString * _Nullable query;

@end
@objcMembers public class EmailEnvelope: NSObject, Codable {

    public var to: [String]?
    public var cc: [String]?
    public var bcc: [String]?
    public var query: String?
}

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.

All methods are non-blocking:

- (void)sendEmailFromTemplateWithTemplateName:(NSString * _Nonnull)templateName
                                     envelope:(EmailEnvelope * _Nonnull)envelope
                              responseHandler:(void (^ _Null_unspecified)(MessageStatus * _Nonnull))responseHandler
                                 errorHandler:(void (^ _Null_unspecified)(Fault * _Nonnull))errorHandler;

- (void)sendEmailFromTemplateWithTemplateName:(NSString * _Nonnull)templateName 
                                     envelope:(EmailEnvelope * _Nonnull)envelope 
                              templateValues:(NSDictionary<NSString *, NSString *> * _Nonnull)templateValues 
                              responseHandler:(void (^ _Null_unspecified)(MessageStatus * _Nonnull))responseHandler
                                 errorHandler:(void (^ _Null_unspecified)(Fault * _Nonnull))errorHandler;
func sendEmailFromTemplate(templateName: String,
                           envelope: EmailEnvelope,
                           responseHandler: ((MessageStatus) -> Void)!,
                           errorHandler: ((Fault) -> Void)!)

func sendEmailFromTemplate(templateName: String,
                           envelope: EmailEnvelope,
                           templateValues: [String : String],
                           responseHandler: ((MessageStatus) -> Void)!,
                           errorHandler: ((Fault) -> Void)!)
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 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.

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 *emailEnvelope = [EmailEnvelope new];
emailEnvelope.query = @"email not like '%@gmail.com and address.country = 'USA'";

[Backendless.shared.messaging
 sendEmailFromTemplateWithTemplateName:@"Marketing Template"
 envelope:emailEnvelope
 responseHandler:^(MessageStatus *status) {
    NSLog(@"Email sent");
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];
let emailEnvelope = EmailEnvelope()
emailEnvelope.query = "email not like '%@gmail.com and address.country = 'USA'"

Backendless.shared.messaging.sendEmailFromTemplate(
    templateName: "Marketing Template",
    envelope: emailEnvelope,
    responseHandler: { status in print("Email sent") },
    errorHandler: { fault in print("Error: \(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" field. It contains two substitution values for the "Users.address.country" and the "discount" placeholders:

EmailEnvelope *emailEnvelope = [EmailEnvelope new];
emailEnvelope.to = @[@"joe@yahoo.com", @"bob@hotmail.com"];

NSDictionary *templateValues = @{@"Users.address.country": @"your country",
                                 @"discount": @"20% off"};

[Backendless.shared.messaging
 sendEmailFromTemplateWithTemplateName:@"Marketing Template"
 envelope:emailEnvelope
 templateValues:templateValues
 responseHandler:^(MessageStatus *status) {
    NSLog(@"Email sent");
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];
let emailEnvelope = EmailEnvelope()
emailEnvelope.to = ["joe@yahoo.com", "bob@hotmail.com"]

let templateValues = ["Users.address.country": "your country",
                      "discount": "20% off"]

Backendless.shared.messaging.sendEmailFromTemplate(
    templateName: "Marketing Template",
    envelope: emailEnvelope,
    templateValues: templateValues,
    responseHandler: { status in print("Email sent") },
    errorHandler: { fault in print("Error: \(fault.message ?? "")")
})