Objective-C
Using Replace Patterns in Email

Demonstrates how to use the replace patterns (mail-merge) feature in Chilkat MailMan.
Chilkat Objective-C Downloads

Objective-C
#import <CkoEmail.h>
#import <CkoMailMan.h>
#import <NSString.h>
#import <CkoJsonObject.h>

BOOL success = NO;

//  This example requires the Chilkat API to have been previously unlocked.
//  See Global Unlock Sample for sample code.

//  ---------------------------------------------------------------------
//  Create an email template for sending.
CkoEmail *emailTemplate = [[CkoEmail alloc] init];

//  We're going to replace "FIRST_NAME" with an actual name.
//  We arbitrarily chose "FIRST_NAME".  We can choose anything, such as "CUSTOMER_NAME" or "THE_RECIPIENT_NAME"...
emailTemplate.Subject = @"Hello FIRST_NAME,";

emailTemplate.From = @"john@example.com";
[emailTemplate AddTo: @"FIRST_NAME" emailAddress: @"RECIPIENT_EMAIL"];

[emailTemplate SetHtmlBody: @"<html><body><h2>Hello FIRST_NAME,</h2><p>Your order for PRODUCT_NAME has been shipped.</p></body></html>"];

//  If the email is saved to a file, we can see what it contains:
[emailTemplate SaveEml: @"qa_output/emailTemplate.eml"];

//  For example:

//  MIME-Version: 1.0
//  Date: Tue, 26 Apr 2022 07:10:52 -0500
//  Message-ID: <715CF231A9F07B0B9FDB073518CD94138D791866@XYZ>
//  Content-Type: text/html; charset=us-ascii
//  Content-Transfer-Encoding: 7bit
//  X-Priority: 3 (Normal)
//  Subject: Hello FIRST_NAME,
//  From: john@example.com
//  To: FIRST_NAME <RECIPIENT_EMAIL>
//  
//  <html><body><h2>Hello FIRST_NAME,</h2><p>Your order for PRODUCT_NAME has been shipped.</p></body></html>

//  ---------------------------------------------------------------------
//  Demonstrate replace patterns by setting and then rendering to MIME.

CkoMailMan *mailman = [[CkoMailMan alloc] init];

[emailTemplate SetReplacePattern: @"FIRST_NAME" replace: @"Elon"];
[emailTemplate SetReplacePattern: @"RECIPIENT_EMAIL" replace: @"elon.musk@example.com"];
[emailTemplate SetReplacePattern: @"PRODUCT_NAME" replace: @"Twitter Corporation"];

//  Render to MIME to see what we get.
//  Note: When the MailMan sends an email, it renders the email to MIME and then sends.
//  The rendering process is to do replacements, or possibly sign, encrypt, etc.
//  When MailMan.SendEmail is called, internally the email is rendered, and the rendered email is sent.
//  The equivalent to MailMan.Send email is to call email.RenderToMime followed by MailMan.SendMime.
NSString *mime = [mailman RenderToMime: emailTemplate];
NSLog(@"%@",mime);

//  This is the rendered MIME:

//  MIME-Version: 1.0
//  Date: Tue, 26 Apr 2022 07:25:49 -0500
//  Message-ID: <750582BCDC891C67B48CEE2293C08B902C3891E9@XYZ>
//  Content-Type: text/html; charset=us-ascii
//  Content-Transfer-Encoding: 7bit
//  X-Priority: 3 (Normal)
//  Subject: Hello Elon,
//  From: john@example.com
//  To: Elon <elon.musk@example.com>
//  
//  <html><body><h2>Hello Elon,</h2><p>Your order for Twitter Corporation has been shipped.</p></body></html>

//  Note: When rendering, the Date and Message-ID headers are automatically regenerated.

//  ---------------------------------------------------------------------
//  An application can see what replacement patterns it previously set by calling SetReplacePattern multiple times.
int count = [emailTemplate.NumReplacePatterns intValue];
NSLog(@"%@%d",@"Number of replace patterns: ",count);

int i = 0;
while (i < count) {
    //  Note: The GetReplaceString method was found to not be working correctly.  It was returning the same value as GetReplacePattern.
    //  It is fixed in Chilkat v9.5.0.91
    NSLog(@"%@%@%@",[emailTemplate GetReplacePattern: [NSNumber numberWithInt: i]],@": ",[emailTemplate GetReplaceString: [NSNumber numberWithInt: i]]);
    i = i + 1;
}

//  Or lookup a replacement pattern by name:
NSString *name = @"FIRST_NAME";
NSLog(@"%@%@%@",name,@" = ",[emailTemplate GetReplaceString2: name]);

//  Sample output:

//  Number of replace patterns: 3
//  FIRST_NAME: Elon
//  RECIPIENT_EMAIL: elon.musk@example.com
//  PRODUCT_NAME: Twitter Corporation
//  FIRST_NAME = Elon

//  ---------------------------------------------------------------------
//  Finally... demonstrate sending emails using the replacement patterns.
//  

//  Set our mail server settings..
mailman.SmtpHost = @"smtp.mail.us-west-2.awsapps.com";
mailman.SmtpSsl = YES;
mailman.SmtpPort = [NSNumber numberWithInt:465];

mailman.SmtpUsername = @"john@example.com";
mailman.SmtpPassword = @"the_password";

//  Imagine we have data in JSON format, and we wish to send the templated email to each recipient...
//  

//  {
//  	"mail_merge" : [
//  		{
//  			"to": "mary@example.com",
//  			"name": "Mary",
//  			"product": "Widget 1" 
//  		},
//  		{
//  			"to": "robert@example.com",
//  			"name": "Robert",
//  			"product": "Widget 2"
//  		}	
//  		...
//  	]
//  }

CkoJsonObject *json = [[CkoJsonObject alloc] init];
success = [json LoadFile: @"qa_data/json/mail_merge.json"];
if (success == NO) {
    NSLog(@"%@",json.LastErrorText);
    return;
}

NSString *emailAddr = 0;
NSString *firstName = 0;
NSString *product = 0;

i = 0;
count = [[json SizeOfArray: @"mail_merge"] intValue];
while (i < count) {
    json.I = [NSNumber numberWithInt: i];
    emailAddr = [json StringOf: @"mail_merge[i].to"];
    firstName = [json StringOf: @"mail_merge[i].name"];
    product = [json StringOf: @"mail_merge[i].product"];

    [emailTemplate SetReplacePattern: @"FIRST_NAME" replace: firstName];
    [emailTemplate SetReplacePattern: @"RECIPIENT_EMAIL" replace: emailAddr];
    [emailTemplate SetReplacePattern: @"PRODUCT_NAME" replace: product];

    success = [mailman SendEmail: emailTemplate];
    if (success == NO) {
        NSLog(@"%@",mailman.LastErrorText);
        return;
    }

    NSLog(@"%@%@",@"Send email to ",emailAddr);

    i = i + 1;
}

NSLog(@"%@",@"Success.");