(Unicode C) Using Replace Patterns in Email

See more Email Object Examples

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

Chilkat C/C++ Library Downloads

MS Visual C/C++

Linux/CentOS C/C++

Alpine Linux C/C++

MAC OS X C/C++

armhf/aarch64 C/C++

C++ Builder

iOS C/C++

Android C/C++

Solaris C/C++

MinGW C/C++

#include <C_CkEmailW.h>
#include <C_CkMailManW.h>
#include <C_CkJsonObjectW.h>

void ChilkatSample(void)
    {
    BOOL success;
    HCkEmailW emailTemplate;
    HCkMailManW mailman;
    const wchar_t *mime;
    int count;
    int i;
    const wchar_t *name;
    HCkJsonObjectW json;
    const wchar_t *emailAddr;
    const wchar_t *firstName;
    const wchar_t *product;

    // 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 = CkEmailW_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"...
    CkEmailW_putSubject(emailTemplate,L"Hello FIRST_NAME,");

    CkEmailW_putFrom(emailTemplate,L"john@example.com");
    CkEmailW_AddTo(emailTemplate,L"FIRST_NAME",L"RECIPIENT_EMAIL");

    CkEmailW_SetHtmlBody(emailTemplate,L"<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:
    CkEmailW_SaveEml(emailTemplate,L"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 = CkMailManW_Create();

    CkEmailW_SetReplacePattern(emailTemplate,L"FIRST_NAME",L"Elon");
    CkEmailW_SetReplacePattern(emailTemplate,L"RECIPIENT_EMAIL",L"elon.musk@example.com");
    CkEmailW_SetReplacePattern(emailTemplate,L"PRODUCT_NAME",L"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 = CkMailManW_renderToMime(mailman,emailTemplate);
    wprintf(L"%s\n",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 = CkEmailW_getNumReplacePatterns(emailTemplate);
    wprintf(L"Number of replace patterns: %d\n",count);

    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
        wprintf(L"%s: %s\n",CkEmailW_getReplacePattern(emailTemplate,i),CkEmailW_getReplaceString(emailTemplate,i));
        i = i + 1;
    }

    // Or lookup a replacement pattern by name:
    name = L"FIRST_NAME";
    wprintf(L"%s = %s\n",name,CkEmailW_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..
    CkMailManW_putSmtpHost(mailman,L"smtp.mail.us-west-2.awsapps.com");
    CkMailManW_putSmtpSsl(mailman,TRUE);
    CkMailManW_putSmtpPort(mailman,465);

    CkMailManW_putSmtpUsername(mailman,L"john@example.com");
    CkMailManW_putSmtpPassword(mailman,L"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 = CkJsonObjectW_Create();
    success = CkJsonObjectW_LoadFile(json,L"qa_data/json/mail_merge.json");
    if (success == FALSE) {
        wprintf(L"%s\n",CkJsonObjectW_lastErrorText(json));
        CkEmailW_Dispose(emailTemplate);
        CkMailManW_Dispose(mailman);
        CkJsonObjectW_Dispose(json);
        return;
    }

    i = 0;
    count = CkJsonObjectW_SizeOfArray(json,L"mail_merge");
    while (i < count) {
        CkJsonObjectW_putI(json,i);
        emailAddr = CkJsonObjectW_stringOf(json,L"mail_merge[i].to");
        firstName = CkJsonObjectW_stringOf(json,L"mail_merge[i].name");
        product = CkJsonObjectW_stringOf(json,L"mail_merge[i].product");

        CkEmailW_SetReplacePattern(emailTemplate,L"FIRST_NAME",firstName);
        CkEmailW_SetReplacePattern(emailTemplate,L"RECIPIENT_EMAIL",emailAddr);
        CkEmailW_SetReplacePattern(emailTemplate,L"PRODUCT_NAME",product);

        success = CkMailManW_SendEmail(mailman,emailTemplate);
        if (success == FALSE) {
            wprintf(L"%s\n",CkMailManW_lastErrorText(mailman));
            CkEmailW_Dispose(emailTemplate);
            CkMailManW_Dispose(mailman);
            CkJsonObjectW_Dispose(json);
            return;
        }

        wprintf(L"Send email to %s\n",emailAddr);

        i = i + 1;
    }

    wprintf(L"Success.\n");


    CkEmailW_Dispose(emailTemplate);
    CkMailManW_Dispose(mailman);
    CkJsonObjectW_Dispose(json);

    }