PureBasic
PureBasic
Using Replace Patterns in Email
See more Email Object Examples
Demonstrates how to use the replace patterns (mail-merge) feature in Chilkat MailMan.Chilkat PureBasic Downloads
IncludeFile "CkJsonObject.pb"
IncludeFile "CkEmail.pb"
IncludeFile "CkMailMan.pb"
Procedure ChilkatExample()
success.i = 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.
emailTemplate.i = CkEmail::ckCreate()
If emailTemplate.i = 0
Debug "Failed to create object."
ProcedureReturn
EndIf
; 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::setCkSubject(emailTemplate, "Hello FIRST_NAME,")
CkEmail::setCkFrom(emailTemplate, "john@example.com")
CkEmail::ckAddTo(emailTemplate,"FIRST_NAME","RECIPIENT_EMAIL")
CkEmail::ckSetHtmlBody(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::ckSaveEml(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.
mailman.i = CkMailMan::ckCreate()
If mailman.i = 0
Debug "Failed to create object."
ProcedureReturn
EndIf
CkEmail::ckSetReplacePattern(emailTemplate,"FIRST_NAME","Elon")
CkEmail::ckSetReplacePattern(emailTemplate,"RECIPIENT_EMAIL","elon.musk@example.com")
CkEmail::ckSetReplacePattern(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.s = CkMailMan::ckRenderToMime(mailman,emailTemplate)
Debug 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.i = CkEmail::ckNumReplacePatterns(emailTemplate)
Debug "Number of replace patterns: " + Str(count)
i.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
Debug CkEmail::ckGetReplacePattern(emailTemplate,i) + ": " + CkEmail::ckGetReplaceString(emailTemplate,i)
i = i + 1
Wend
; Or lookup a replacement pattern by name:
name.s = "FIRST_NAME"
Debug name + " = " + CkEmail::ckGetReplaceString2(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::setCkSmtpHost(mailman, "smtp.mail.us-west-2.awsapps.com")
CkMailMan::setCkSmtpSsl(mailman, 1)
CkMailMan::setCkSmtpPort(mailman, 465)
CkMailMan::setCkSmtpUsername(mailman, "john@example.com")
CkMailMan::setCkSmtpPassword(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.i = CkJsonObject::ckCreate()
If json.i = 0
Debug "Failed to create object."
ProcedureReturn
EndIf
success = CkJsonObject::ckLoadFile(json,"qa_data/json/mail_merge.json")
If success = 0
Debug CkJsonObject::ckLastErrorText(json)
CkEmail::ckDispose(emailTemplate)
CkMailMan::ckDispose(mailman)
CkJsonObject::ckDispose(json)
ProcedureReturn
EndIf
emailAddr.s
firstName.s
product.s
i = 0
count = CkJsonObject::ckSizeOfArray(json,"mail_merge")
While i < count
CkJsonObject::setCkI(json, i)
emailAddr = CkJsonObject::ckStringOf(json,"mail_merge[i].to")
firstName = CkJsonObject::ckStringOf(json,"mail_merge[i].name")
product = CkJsonObject::ckStringOf(json,"mail_merge[i].product")
CkEmail::ckSetReplacePattern(emailTemplate,"FIRST_NAME",firstName)
CkEmail::ckSetReplacePattern(emailTemplate,"RECIPIENT_EMAIL",emailAddr)
CkEmail::ckSetReplacePattern(emailTemplate,"PRODUCT_NAME",product)
success = CkMailMan::ckSendEmail(mailman,emailTemplate)
If success = 0
Debug CkMailMan::ckLastErrorText(mailman)
CkEmail::ckDispose(emailTemplate)
CkMailMan::ckDispose(mailman)
CkJsonObject::ckDispose(json)
ProcedureReturn
EndIf
Debug "Send email to " + emailAddr
i = i + 1
Wend
Debug "Success."
CkEmail::ckDispose(emailTemplate)
CkMailMan::ckDispose(mailman)
CkJsonObject::ckDispose(json)
ProcedureReturn
EndProcedure