(Delphi DLL) Using Replace Patterns in Email

See more Email Object Examples

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

Chilkat for Delphi Downloads

Chilkat non-ActiveX DLL for Delphi

Chilkat ActiveX DLL for Delphi

* The examples here use the non-ActiveX DLL.

uses
    Winapi.Windows, Winapi.Messages, System.SysUtils, System.Variants, System.Classes, Vcl.Graphics,
    Vcl.Controls, Vcl.Forms, Vcl.Dialogs, Vcl.StdCtrls, MailMan, Email, JsonObject;

...

procedure TForm1.Button1Click(Sender: TObject);
var
success: Boolean;
emailTemplate: HCkEmail;
mailman: HCkMailMan;
mime: PWideChar;
count: Integer;
i: Integer;
name: PWideChar;
json: HCkJsonObject;
emailAddr: PWideChar;
firstName: PWideChar;
product: PWideChar;

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

// ---------------------------------------------------------------------
// Create an email template for sending.
emailTemplate := CkEmail_Create();

// 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"...
CkEmail_putSubject(emailTemplate,'Hello FIRST_NAME,');

CkEmail_putFrom(emailTemplate,'john@example.com');
CkEmail_AddTo(emailTemplate,'FIRST_NAME','RECIPIENT_EMAIL');

CkEmail_SetHtmlBody(emailTemplate,'<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:
CkEmail_SaveEml(emailTemplate,'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
// CKX-Bounce-Address: 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>

// Note: Ignore the CKX-Bounce-Address header.  It is automatically removed by Chilkat prior to sending.
// All "CKX-" headers are automatically removed prior to sending.

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

mailman := CkMailMan_Create();

CkEmail_SetReplacePattern(emailTemplate,'FIRST_NAME','Elon');
CkEmail_SetReplacePattern(emailTemplate,'RECIPIENT_EMAIL','elon.musk@example.com');
CkEmail_SetReplacePattern(emailTemplate,'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.
mime := CkMailMan__renderToMime(mailman,emailTemplate);
Memo1.Lines.Add(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.
count := CkEmail_getNumReplacePatterns(emailTemplate);
Memo1.Lines.Add('Number of replace patterns: ' + IntToStr(count));

i := 0;
while i < count do
  begin
    // 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
    Memo1.Lines.Add(CkEmail__getReplacePattern(emailTemplate,i) + ': ' + CkEmail__getReplaceString(emailTemplate,i));
    i := i + 1;
  end;

// Or lookup a replacement pattern by name:
name := 'FIRST_NAME';
Memo1.Lines.Add(name + ' = ' + CkEmail__getReplaceString2(emailTemplate,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..
CkMailMan_putSmtpHost(mailman,'smtp.mail.us-west-2.awsapps.com');
CkMailMan_putSmtpSsl(mailman,True);
CkMailMan_putSmtpPort(mailman,465);

CkMailMan_putSmtpUsername(mailman,'john@example.com');
CkMailMan_putSmtpPassword(mailman,'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"
// 		}	
// 		...
// 	]
// }

json := CkJsonObject_Create();
success := CkJsonObject_LoadFile(json,'qa_data/json/mail_merge.json');
if (success = False) then
  begin
    Memo1.Lines.Add(CkJsonObject__lastErrorText(json));
    Exit;
  end;

i := 0;
count := CkJsonObject_SizeOfArray(json,'mail_merge');
while i < count do
  begin
    CkJsonObject_putI(json,i);
    emailAddr := CkJsonObject__stringOf(json,'mail_merge[i].to');
    firstName := CkJsonObject__stringOf(json,'mail_merge[i].name');
    product := CkJsonObject__stringOf(json,'mail_merge[i].product');

    CkEmail_SetReplacePattern(emailTemplate,'FIRST_NAME',firstName);
    CkEmail_SetReplacePattern(emailTemplate,'RECIPIENT_EMAIL',emailAddr);
    CkEmail_SetReplacePattern(emailTemplate,'PRODUCT_NAME',product);

    success := CkMailMan_SendEmail(mailman,emailTemplate);
    if (success = False) then
      begin
        Memo1.Lines.Add(CkMailMan__lastErrorText(mailman));
        Exit;
      end;

    Memo1.Lines.Add('Send email to ' + emailAddr);

    i := i + 1;
  end;

Memo1.Lines.Add('Success.');

CkEmail_Dispose(emailTemplate);
CkMailMan_Dispose(mailman);
CkJsonObject_Dispose(json);

end;