(Perl) Using Replace Patterns in Email

See more Email Object Examples

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

Chilkat Perl Downloads

Perl Module for Windows, MacOS, Linux, Alpine Linux, Solaris

use chilkat();

# 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 = chilkat::CkEmail->new();

# 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->put_Subject("Hello FIRST_NAME,");

$emailTemplate->put_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
# 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 = chilkat::CkMailMan->new();

$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.
$mime = $mailman->renderToMime($emailTemplate);
print $mime . "\r\n";

# 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 = $emailTemplate->get_NumReplacePatterns();
print "Number of replace patterns: " . $count . "\r\n";

$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) . "\r\n";
    $i = $i + 1;
}

# Or lookup a replacement pattern by name:
$name = "FIRST_NAME";
print $name . " = " . $emailTemplate->getReplaceString2($name) . "\r\n";

# 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->put_SmtpHost("smtp.mail.us-west-2.awsapps.com");
$mailman->put_SmtpSsl(1);
$mailman->put_SmtpPort(465);

$mailman->put_SmtpUsername('john@example.com');
$mailman->put_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"
# 		}	
# 		...
# 	]
# }

$json = chilkat::CkJsonObject->new();
$success = $json->LoadFile("qa_data/json/mail_merge.json");
if ($success == 0) {
    print $json->lastErrorText() . "\r\n";
    exit;
}

$i = 0;
$count = $json->SizeOfArray("mail_merge");
while ($i < $count) {
    $json->put_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);

    $success = $mailman->SendEmail($emailTemplate);
    if ($success == 0) {
        print $mailman->lastErrorText() . "\r\n";
        exit;
    }

    print "Send email to " . $emailAddr . "\r\n";

    $i = $i + 1;
}

print "Success." . "\r\n";