Dart
Using Replace Patterns in Email

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

Dart
import 'package:chilkat/chilkat.dart';

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

  // ---------------------------------------------------------------------
  // Create an email template for sending.
  final emailTemplate = CkEmail();

  // 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', '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.

  final mailman = CkMailMan();

  emailTemplate.setReplacePattern('FIRST_NAME', 'Elon');
  emailTemplate.setReplacePattern('RECIPIENT_EMAIL', 'elon.musk@example.com');
  emailTemplate.setReplacePattern('PRODUCT_NAME', '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.
  final mime = mailman.renderToMime(emailTemplate);
  print(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.
  var count = emailTemplate.numReplacePatterns;
  print('Number of replace patterns: $count');

  var 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
    print('${emailTemplate.getReplacePattern(i)}: ${emailTemplate.getReplaceString(i)}');
    i++;
  }

  // Or lookup a replacement pattern by name:
  final name = 'FIRST_NAME';
  print('$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 = true;
  mailman.smtpPort = 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"
  // 		}	
  // 		...
  // 	]
  // }

  final json = CkJsonObject();
  try {
    json.loadFile('qa_data/json/mail_merge.json');
  } on ChilkatException catch (e) {
    print(e.lastErrorText);
    return;
  }

  var emailAddr = '';
  var firstName = '';
  var product = '';

  i = 0;
  count = json.sizeOfArray('mail_merge');
  while (i < count) {
    json.i = 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', firstName);
    emailTemplate.setReplacePattern('RECIPIENT_EMAIL', emailAddr);
    emailTemplate.setReplacePattern('PRODUCT_NAME', product);

    try {
      mailman.sendEmail(emailTemplate);
    } on ChilkatException catch (e) {
      print(e.lastErrorText);
      return;
    }

    print('Send email to $emailAddr');

    i++;
  }

  print('Success.');
}