Xbase++
Using Replace Patterns in Email

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

Xbase++
LOCAL nSuccess
LOCAL oEmailTemplate
LOCAL oMailman
LOCAL cMime
LOCAL nCount
LOCAL i
LOCAL cName
LOCAL oJson
LOCAL cEmailAddr
LOCAL cFirstName
LOCAL cProduct

nSuccess := 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.
oEmailTemplate := CreateObject("Chilkat.Email")

//  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"...
oEmailTemplate:Subject := "Hello FIRST_NAME,"

oEmailTemplate:From := "john@example.com"
oEmailTemplate:AddTo("FIRST_NAME", "RECIPIENT_EMAIL")

oEmailTemplate: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:
oEmailTemplate: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.

oMailman := CreateObject("Chilkat.MailMan")

oEmailTemplate:SetReplacePattern("FIRST_NAME", "Elon")
oEmailTemplate:SetReplacePattern("RECIPIENT_EMAIL", "elon.musk@example.com")
oEmailTemplate: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.
cMime := oMailman:RenderToMime(oEmailTemplate)
? cMime

//  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.
nCount := oEmailTemplate:NumReplacePatterns
? "Number of replace patterns: " + Str(nCount)

i := 0
DO WHILE i < nCount
    //  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
    ? oEmailTemplate:GetReplacePattern(i) + ": " + oEmailTemplate:GetReplaceString(i)
    i := i + 1
ENDDO

//  Or lookup a replacement pattern by name:
cName := "FIRST_NAME"
? cName + " = " + oEmailTemplate:GetReplaceString2(cName)

//  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..
oMailman:SmtpHost := "smtp.mail.us-west-2.awsapps.com"
oMailman:SmtpSsl := 1
oMailman:SmtpPort := 465

oMailman:SmtpUsername := "john@example.com"
oMailman: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"
//  		}	
//  		...
//  	]
//  }

oJson := CreateObject("Chilkat.JsonObject")
nSuccess := oJson:LoadFile("qa_data/json/mail_merge.json")
IF (nSuccess == 0)
    ? oJson:LastErrorText
    oEmailTemplate:destroy()
    oMailman:destroy()
    oJson:destroy()
    RETURN
ENDIF

i := 0
nCount := oJson:SizeOfArray("mail_merge")
DO WHILE i < nCount
    oJson:I := i
    cEmailAddr := oJson:StringOf("mail_merge[i].to")
    cFirstName := oJson:StringOf("mail_merge[i].name")
    cProduct := oJson:StringOf("mail_merge[i].product")

    oEmailTemplate:SetReplacePattern("FIRST_NAME", cFirstName)
    oEmailTemplate:SetReplacePattern("RECIPIENT_EMAIL", cEmailAddr)
    oEmailTemplate:SetReplacePattern("PRODUCT_NAME", cProduct)

    nSuccess := oMailman:SendEmail(oEmailTemplate)
    IF (nSuccess == 0)
        ? oMailman:LastErrorText
        oEmailTemplate:destroy()
        oMailman:destroy()
        oJson:destroy()
        RETURN
    ENDIF

    ? "Send email to " + cEmailAddr

    i := i + 1
ENDDO

? "Success."

oEmailTemplate:destroy()
oMailman:destroy()
oJson:destroy()