Tcl
Using Replace Patterns in Email

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

Tcl

load ./chilkat.dll

set success 0

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

# ---------------------------------------------------------------------
# Create an email template for sending.
set emailTemplate [new_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"...
CkEmail_put_Subject $emailTemplate "Hello FIRST_NAME,"

CkEmail_put_From $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
# 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.

set mailman [new_CkMailMan]

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.
set mime [CkMailMan_renderToMime $mailman $emailTemplate]
puts "$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.
set count [CkEmail_get_NumReplacePatterns $emailTemplate]
puts "Number of replace patterns: $count"

set 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
    puts [CkEmail_getReplacePattern $emailTemplate $i]: [CkEmail_getReplaceString $emailTemplate $i]
    set i [expr $i + 1]
}

# Or lookup a replacement pattern by name:
set name "FIRST_NAME"
puts "$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_put_SmtpHost $mailman "smtp.mail.us-west-2.awsapps.com"
CkMailMan_put_SmtpSsl $mailman 1
CkMailMan_put_SmtpPort $mailman 465

CkMailMan_put_SmtpUsername $mailman "john@example.com"
CkMailMan_put_SmtpPassword $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"
# 		}	
# 		...
# 	]
# }

set json [new_CkJsonObject]

set success [CkJsonObject_LoadFile $json "qa_data/json/mail_merge.json"]
if {$success == 0} then {
    puts [CkJsonObject_lastErrorText $json]
    delete_CkEmail $emailTemplate
    delete_CkMailMan $mailman
    delete_CkJsonObject $json
    exit
}

set i 0
set count [CkJsonObject_SizeOfArray $json "mail_merge"]
while {$i < $count} {
    CkJsonObject_put_I $json $i
    set emailAddr [CkJsonObject_stringOf $json "mail_merge[i].to"]
    set firstName [CkJsonObject_stringOf $json "mail_merge[i].name"]
    set 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

    set success [CkMailMan_SendEmail $mailman $emailTemplate]
    if {$success == 0} then {
        puts [CkMailMan_lastErrorText $mailman]
        delete_CkEmail $emailTemplate
        delete_CkMailMan $mailman
        delete_CkJsonObject $json
        exit
    }

    puts "Send email to $emailAddr"

    set i [expr $i + 1]
}

puts "Success."

delete_CkEmail $emailTemplate
delete_CkMailMan $mailman
delete_CkJsonObject $json