Skip to main content

Template Helper Functions

Postchi provides powerful template helper functions for encoding, hashing, and transforming data within your email templates. These helpers enable secure personalization, GDPR-compliant tracking, and seamless third-party integrations.

Table of Contents​

Basic Variables​

Before diving into helpers, remember that Postchi supports simple variable replacement:

Hello {{firstName}}!
Your email is {{contact.email}}

Available contact variables:

  • {{email}} or {{contact.email}} - Contact email address
  • {{firstName}} or {{contact.firstName}} - Contact first name
  • {{lastName}} or {{contact.lastName}} - Contact last name
  • {{customFieldName}} or {{contact.customFieldName}} - Any custom field

Helper Functions​

Hash​

Generate cryptographic hashes for secure, anonymized identifiers.

Supported Algorithms: md5, sha1, sha256, sha512

Syntax:

{{#hash "algorithm"}}content{{/hash}}

Examples:

<!-- SHA-256 hash of email (recommended) -->
{{#hash "sha256"}}{{contact.email}}{{/hash}}
<!-- Output: 973dfe463ec85785f5f95af5ba3906eedb2d931c24e69824a89ea65dba4e813b -->

<!-- MD5 hash (faster but less secure) -->
{{#hash "md5"}}{{contact.email}}{{/hash}}
<!-- Output: 55502f40dc8b7c769880b10874abc9d0 -->

<!-- Hash literal text -->
{{#hash "sha256"}}my-unique-identifier{{/hash}}

Use Cases:

  • GDPR-compliant analytics tracking
  • Anonymized user identifiers
  • Privacy-preserving third-party integrations

HMAC​

Generate Hash-based Message Authentication Codes (HMAC) for secure tokens requiring authentication.

Supported Algorithms: sha1, sha256, sha512

Syntax:

{{#hmac "algorithm" "secret-key"}}content{{/hmac}}

Examples:

<!-- HMAC SHA-256 with secret -->
{{#hmac "sha256" "my-secret-key"}}{{contact.email}}{{/hmac}}
<!-- Output: 2e1a4b6c25fc8e5ba0d79a5f9d5913e8c9e6c68f4d0a5c5e9b1f3d8a7c4e2f1a -->

<!-- Create secure unsubscribe token -->
{{#hmac "sha256" "unsubscribe-secret-2024"}}{{contact.email}}{{/hmac}}

Use Cases:

  • Secure authentication tokens
  • Signed unsubscribe links
  • Webhook payload verification
  • API request signing

Security Note: HMAC is more secure than plain hashing because it requires a secret key, preventing rainbow table attacks.

Base64​

Encode and decode data using Base64 encoding.

Encode Syntax:

{{#base64}}content{{/base64}}

Decode Syntax:

{{#base64Decode}}content{{/base64Decode}}

Examples:

<!-- Encode email -->
{{#base64}}{{contact.email}}{{/base64}}
<!-- Output: dGVzdEBleGFtcGxlLmNvbQ== -->

<!-- Decode Base64 string -->
{{#base64Decode}}dGVzdEBleGFtcGxlLmNvbQ=={{/base64Decode}}
<!-- Output: test@example.com -->

<!-- Encode literal text -->
{{#base64}}Hello World{{/base64}}
<!-- Output: SGVsbG8gV29ybGQ= -->

Use Cases:

  • Encoding data in URL parameters
  • Obfuscating email addresses in links
  • Binary data transmission

URL Encoding​

Encode and decode strings for safe use in URLs.

Encode Syntax:

{{#urlEncode}}content{{/urlEncode}}

Decode Syntax:

{{#urlDecode}}content{{/urlDecode}}

Examples:

<!-- URL encode email -->
{{#urlEncode}}{{contact.email}}{{/urlEncode}}
<!-- Output: test%40example.com -->

<!-- URL encode with special characters -->
{{#urlEncode}}Hello World! #$%{{/urlEncode}}
<!-- Output: Hello%20World!%20%23%24%25 -->

<!-- Decode URL-encoded string -->
{{#urlDecode}}test%40example.com{{/urlDecode}}
<!-- Output: test@example.com -->

Use Cases:

  • Passing data in URL query parameters
  • Email tracking links
  • Redirect URLs with parameters

JSON​

Convert variables to JSON format, optionally with URL encoding.

JSON Syntax:

{{#toJson}}{{variable}}{{/toJson}}

URL-Encoded JSON Syntax:

{{#toUrlEncodedJson}}{{variable}}{{/toUrlEncodedJson}}

Examples:

<!-- Convert object to JSON -->
{{#toJson}}{{contact}}{{/toJson}}
<!-- Output: {"email":"test@example.com","firstName":"John","lastName":"Doe"} -->

<!-- Convert and URL encode for safe URL passing -->
{{#toUrlEncodedJson}}{{contact}}{{/toUrlEncodedJson}}
<!-- Output: %7B%22email%22%3A%22test%40example.com%22%2C%22firstName%22%3A%22John%22%7D -->

Use Cases:

  • Passing structured data to webhooks
  • Embedding contact data in redirect URLs
  • JavaScript data initialization

Real-World Use Cases​

1. Privacy-Preserving Analytics Tracking​

Hash email addresses before sending to analytics services:

<!-- Google Analytics tracking pixel with hashed user ID -->
<img src="https://www.google-analytics.com/collect?v=1&tid=UA-XXXXX&cid={{#hash "sha256"}}{{contact.email}}{{/hash}}&t=event" />

<!-- Custom analytics with anonymized identifier -->
<a href="https://yoursite.com/page?user_id={{#hash "sha256"}}{{contact.email}}{{/hash}}">
  Visit Our Site
</a>

Create authenticated unsubscribe links:

<!-- HMAC-secured unsubscribe link -->
<a href="https://yoursite.com/unsubscribe?email={{#base64}}{{contact.email}}{{/base64}}&token={{#hmac "sha256" "unsubscribe-secret"}}{{contact.email}}{{/hmac}}">
  Unsubscribe
</a>

3. Third-Party Integration with Contact Data​

Pass contact information to external services:

<!-- Webhook callback with contact data -->
<a href="https://partner.com/callback?data={{#toUrlEncodedJson}}{{contact}}{{/toUrlEncodedJson}}">
  Complete Registration
</a>

<!-- CRM sync with Base64-encoded email -->
<img src="https://crm.example.com/sync?id={{#base64}}{{contact.email}}{{/base64}}" />

Combine multiple helpers for complex use cases:

<!-- Multi-factor tracking link -->
<a href="https://yoursite.com/click?campaign=summer2024&user={{#hash "md5"}}{{contact.email}}{{/hash}}&ref={{#urlEncode}}{{campaign.name}}{{/urlEncode}}">
  Click Here
</a>

5. GDPR-Compliant Facebook Pixel​

Hash PII before sending to Facebook:

<script>
  fbq('track', 'PageView', {
    em: '{{#hash "sha256"}}{{contact.email}}{{/hash}}',
    fn: '{{#hash "sha256"}}{{contact.firstName}}{{/hash}}',
    ln: '{{#hash "sha256"}}{{contact.lastName}}{{/hash}}'
  });
</script>

6. Nested Helpers for Complex Transformations​

Chain helpers for advanced use cases:

<!-- Base64 encode a SHA-256 hash -->
{{#base64}}{{#hash "sha256"}}{{contact.email}}{{/hash}}{{/base64}}

<!-- URL encode a JSON object -->
https://api.example.com/webhook?payload={{#urlEncode}}{{#toJson}}{{contact}}{{/toJson}}{{/urlEncode}}

Security Best Practices​

1. Choose the Right Hash Algorithm​

  • SHA-256: Best balance of security and performance (recommended)
  • SHA-512: Maximum security for sensitive data
  • MD5: Fast but cryptographically weak (only use for non-security purposes)
  • SHA-1: Deprecated, avoid for security-critical applications

2. Use HMAC for Authentication​

When you need to verify data authenticity:

<!-- ✅ GOOD: HMAC with secret -->
{{#hmac "sha256" "secret-key"}}{{contact.email}}{{/hmac}}

<!-- ❌ BAD: Plain hash can be forged -->
{{#hash "sha256"}}{{contact.email}}{{/hash}}

3. Protect Secret Keys​

  • Never hardcode secrets in templates shared with customers
  • Rotate HMAC secrets periodically
  • Use different secrets for different purposes (unsubscribe, webhooks, etc.)

4. GDPR Compliance​

When sending data to third parties:

<!-- ✅ GOOD: Hash before sending to analytics -->
<img src="https://analytics.example.com/pixel?uid={{#hash "sha256"}}{{contact.email}}{{/hash}}" />

<!-- ❌ BAD: Sending plain email violates GDPR -->
<img src="https://analytics.example.com/pixel?email={{contact.email}}" />

5. URL Encoding for Special Characters​

Always URL encode when passing data in URLs:

<!-- ✅ GOOD: URL encoded -->
https://example.com/redirect?email={{#urlEncode}}{{contact.email}}{{/urlEncode}}

<!-- ❌ BAD: @ symbol breaks URL -->
https://example.com/redirect?email={{contact.email}}

Template Testing​

You can test templates with helper functions using the "Test Email" feature in the Postchi dashboard:

  1. Navigate to Templates → Your Template → Test Email
  2. Enter test contact data (email, firstName, lastName, custom fields)
  3. Send test email to verify helper outputs

Example Test Variables:

{
  "email": "test@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

API Integration​

When sending emails via the API, variables are automatically processed with helpers:

curl -X POST https://api.postchi.io/v1/emails/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "templateId": "your-template-id",
    "variables": {
      "firstName": "John",
      "campaign": {
        "name": "Summer Sale 2024"
      }
    }
  }'

The template content will automatically process all helper functions with the provided variables.

Performance Considerations​

Hash Performance​

From fastest to slowest:

  1. MD5 - ~10x faster than SHA-256 (but less secure)
  2. SHA-256 - Good balance (recommended)
  3. SHA-512 - Slower but more secure

Caching Strategy​

Postchi automatically caches processed templates. Helper functions are re-evaluated for each email with contact-specific data.

Best Practices​

  • Use simpler hashes (MD5) for non-security purposes
  • Minimize nested helpers when possible
  • Cache helper results in your application if calling API frequently

Support​

For questions or issues with template helpers:

Changelog​

v1.0.0 - Initial release

  • Hash helpers (md5, sha1, sha256, sha512)
  • HMAC helpers (sha1, sha256, sha512)
  • Base64 encoding/decoding
  • URL encoding/decoding
  • JSON conversion
  • URL-encoded JSON conversion