Merge fields when sending relays

[Jericho]

This is a feature they offer when sending mailings (AKA bulk emails), but not when sending relays (AKA transact emails). The library should parse the HTML content, the text content and also the subject line and merge data like "Dear [firstname]" for example.

• [x] Delimiters
• [x] Fallback
• [x] Formatting (for numeric values and dates)

[Jericho]

What should we use for field delimiters?

• CakeMail uses square brackets when sending bulk emails (e.g.: [firstname])
• CampaignMonitor also uses square brackets
• Mandrill/Mailchimp uses a star and 'pipe' (e.g.: *|firstname|*)
• SendGrid allows you to use any delimiter you want but most of their code samples use either a dash, the percent sign or greatherthan/lessthan and percent sign (e.g.: -firstname-, %firstname% or <%firstname%>)
• Hubspot uses two curly brackets (e.g.: {{ firstname }})

I think we should at least support CakeMail's delimiters in order to be consistent with bulk emails but it would be nice to follow SendGrid's lead and allow any delimiter to be used.

[Jericho]

What syntax should we use to define fallback values? (fallback is used when no value is specified for a given merge field.

• CakeMail simply requires a comma between the name of the field and the fallback like so: Dear [firstname, friend]
• CampaignMonitor requires a comma and also 'fallback='. eg: Dear [firstname, fallback=friend]
• Mandrill/Mailchimp doesn't allow you to define a fallback value in the content but they do provide a way to specify default values with a API call
• SendGrid doesn't seem to support fallback values.

I think supporting CakeMail syntax should be good enough.

[Jericho]

Other idea: instead of defining our own syntax for delimiters, fallback values, etc. why not simply use Shopify's open-source template language which would allow us to use existing nuget packages such as dotLiquit for merging data and content.

[Jericho]

How should we allow a format for numeric and date values to be specified?

• CakeMail uses PHP's format string to allow formatting the current day when sending bulk emails but, as far as I can tell, formatting is not available for custom date or numeric fields (e.g.: [DATE|0|Y-m-d])
• Mailchimp uses the same PHP format for the current date, just like CakeMail does: *|DATE:d/m/y|*
• The Liquid template markup supports formatting dates: {{ article.published_at | date: "%Y" }}

[beriniwlew]

For field delimiters, I say it should be CakeMail's format. Keep it consistent. The same should be done for the fallback values.

[Jericho]

Fair enough. Here's what I propose:

• Add a parameter called mergeData to the SendWithTrackingAsync and SendWithoutTrackingAsync methods
• The type of this new parameter will be IDictionary<string, object>
• The key of this dictionary is the name of the fields like firstname for example
• The reason why I propose object for data type is so we can support string, numeric and dates
• When sending a relay (AKA a transact email), the library will automatically parse the subject, the HTML and the text content and replace each field with the appropriate value
• If data for a given merge field is not provided, we use the fallback and if the fallback is not provided, we default to string.empty

[Jericho]

I'm completing testing. You will be able to:

• merge any field and specify a fallback value
• merge numeric fields (such as int, long, float, etc.), specify a default value and/or specify a format. We support .NET standard numeric formats and custom numeric formats
• merge date fields, specify a default value and/or specify a format. We support .NET standard date/time formats and custom date/time formats
• additionally, we support a merge field for the current date and time in the UTC timezone (you can use DATE, TODAY or NOW interchangeably).

Here are just a few examples that we support: String field: [firstname], [firstname,friend] Date field: [customer_since], [customer_since | yyyy-MM-dd], [customer_since,yesterday | yyyy-MM-dd] Numeric field: [miles_driven], [miles_driven | #,#], [miles_driven, 0 | #,#] Current date and time with default format: [DATE], [TODAY], [NOW] Current date and time with custom format: [DATE | yyyy-MM-dd], [TODAY | yyyy-MM-dd], [NOW | yyyy-MM-dd]