Personalize Emails

{
  "from": {
    "email": "richard@piedpiper.com",
    "name": "Richard"
  },
  "to": [
    {
      "email": "gavin@hooli.com",
      "name": "Gavin Belson",
      "customFields": {
        "firstName": "Gavin",
        "discountCode": "BELSON240",
        "status": "VIP"
      }
    },
    {
      "email": "erlich@piedpiper.com",
      "name": "Erlich Bachman",
      "customFields": {
        "firstName": "Erlich",
        "discountCode": "BACHMAN10",
        "status": "Incubator"
      }
    },
  ],
  "subject": "Hello, {{firstName}}! Welcome to Pied Piper!",
  "htmlBody": "<p>Hi {{firstName}},</p><p>Your discount code is <b>{{discountCode}}</b>. Your account status is {{status}}.</p>",
  "textBody": "Hi {{firstName}},\n\nYour discount code is {{discountCode}}. Your account status is {{status}}.",
  "ippool": "default",
  "trackOpens": true,
  "trackClicks": true,
  "groups": [
    "special-offers"
  ]
}

How It Works

Add a customFields object to each recipient in the to array. Use Handlebars syntax ({{variableName}}) in your subject, htmlBody, and textBody to reference these fields. SendPost replaces the placeholders with values from each recipient’s customFields object.

Output

gavin@hooli.com:

Subject: Hello, Gavin! Welcome to Pied Piper!
Body: Hi Gavin, Your discount code is BELSON240. Your account status is VIP.

erlich@piedpiper.com:

Subject: Hello, Erlich! Welcome to Pied Piper!
Body: Hi Erlich, Your discount code is BACHMAN10. Your account status is Incubator.

Advanced Personalization

Nested Fields

Access nested properties in customFields using dot notation. Example:

{
  "from": {
    "email": "noreply@sendpost.io",
    "name": "SendPost Team"
  },
  "to": [
    {
      "email": "john@example.com",
      "name": "John Doe",
      "customFields": {
        "user": {
          "firstName": "John",
          "lastName": "Doe",
          "address": {
            "city": "San Francisco",
            "state": "CA"
          }
        }
      }
    }
  ],
  "subject": "Welcome {{user.firstName}}!",
  "htmlBody": "<h1>Hello {{user.firstName}} {{user.lastName}}!</h1><p>We see you're located in {{user.address.city}}, {{user.address.state}}.</p>",
  "textBody": "Hello {{user.firstName}} {{user.lastName}}!\n\nWe see you're located in {{user.address.city}}, {{user.address.state}}."
}

Output:

Subject: Welcome John!
HTML: Hello John Doe! We see you’re located in San Francisco, CA.

Array Iteration

Iterate over arrays in customFields using the {{#each}} helper. Example:

{
  "to": [
    {
      "email": "alice@example.com",
      "name": "Alice Johnson",
      "customFields": {
        "firstName": "Alice",
        "orders": [
          {
            "id": "ORD-001",
            "product": "Premium Plan",
            "amount": 99.99
          },
          {
            "id": "ORD-002",
            "product": "Add-on Storage",
            "amount": 29.99
          }
        ]
      }
    }
  ],
  "subject": "{{firstName}}, Your Order History",
  "htmlBody": "<h2>Your Recent Orders</h2><ul>{{#each orders}}<li>{{id}}: {{product}} - ${{amount}}</li>{{/each}}</ul>",
  "textBody": "Your Recent Orders:\n\n{{#each orders}}{{id}}: {{product}} - ${{amount}}\n{{/each}}"
}

Output:

Subject: Alice, Your Order History
HTML:
- ORD-001: Premium Plan - $99.99
- ORD-002: Add-on Storage - $29.99

Nested Objects With Arrays

Combine nested objects and arrays for complex data structures. Example:

{
  "to": [
    {
      "email": "bob@example.com",
      "name": "Bob Wilson",
      "customFields": {
        "order": {
          "id": "ORD-12345",
          "customer": {
            "firstName": "Bob",
            "shipping": {
              "address": {
                "city": "New York",
                "state": "NY"
              }
            }
          },
          "items": [
            {
              "name": "Product A",
              "price": 79.99,
              "quantity": 1
            },
            {
              "name": "Product B",
              "price": 29.99,
              "quantity": 2
            }
          ],
          "total": 139.97
        }
      }
    }
  ],
  "subject": "Order {{order.id}} Confirmed - Thank You {{order.customer.firstName}}!",
  "htmlBody": "<h1>Order Confirmation</h1><p>Hi {{order.customer.firstName}},</p><p>Your order {{order.id}} has been confirmed.</p><h2>Items:</h2><ul>{{#each order.items}}<li>{{name}} - ${{price}} (Qty: {{quantity}})</li>{{/each}}</ul><p>Shipping to: {{order.customer.shipping.address.city}}, {{order.customer.shipping.address.state}}</p><p><strong>Total: ${{order.total}}</strong></p>",
  "textBody": "Order Confirmation\n\nHi {{order.customer.firstName}},\n\nYour order {{order.id}} has been confirmed.\n\nItems:\n{{#each order.items}}{{name}} - ${{price}} (Qty: {{quantity}})\n{{/each}}\nShipping to: {{order.customer.shipping.address.city}}, {{order.customer.shipping.address.state}}\n\nTotal: ${{order.total}}"
}

Output:

Subject: Order ORD-12345 Confirmed - Thank You Bob!
HTML: Order confirmation with customer info, items list, shipping address, and total

Syntax Reference

Basic Syntax

Variables: {{variableName}}
Nested properties: {{object.property}} or {{object.nested.property}}
Array iteration: {{#each arrayName}}...{{/each}}
Current item: {{this}} (inside {{#each}})
Array index: {{@index}} (0-based, inside {{#each}})
Conditionals: {{#if condition}}...{{/if}} or {{#if condition}}...{{else}}...{{/if}}

Common Patterns

Iterate over array:

{{#each items}}
  <li>{{this}}</li>
{{/each}}

Iterate over array of objects:

{{#each orders}}
  <p>{{id}}: {{product}} - ${{amount}}</p>
{{/each}}

Check if array has items:

{{#if items}}
  {{#each items}}
    <li>{{this}}</li>
  {{/each}}
{{else}}
  <p>No items found.</p>
{{/if}}

Nested iteration:

{{#each categories}}
  <h3>{{name}}</h3>
  <ul>
    {{#each products}}
      <li>{{this}}</li>
    {{/each}}
  </ul>
{{/each}}

Important Notes

unsubscribe is a reserved custom field name. You can’t use it as a custom field name.

Case sensitivity: Field names are case-sensitive. {{firstName}} and {{FirstName}} are different.
Empty arrays: Empty arrays don’t render anything in {{#each}} blocks. Use {{#if}} to check for empty arrays.
Null/undefined values: If a nested property doesn’t exist, an empty string is rendered. Use {{#if}} to check for existence.
Data structure: Ensure your customFields structure matches your template expectations. Nested objects and arrays must be valid JSON.

Documentation

Guides

SDK Quickstarts

Common Use Cases

How It Works

Output

Advanced Personalization

Nested Fields

Array Iteration

Nested Objects With Arrays

Syntax Reference

Basic Syntax

Common Patterns

Important Notes

​How It Works

​Output

​Advanced Personalization

​Nested Fields

​Array Iteration

​Nested Objects With Arrays

​Syntax Reference

​Basic Syntax

​Common Patterns

​Important Notes

How It Works

Output

Advanced Personalization

Nested Fields

Array Iteration

Nested Objects With Arrays

Syntax Reference

Basic Syntax

Common Patterns

Important Notes