> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendpost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Personalize Emails

> Use Handlebars templating to personalize email content in the subject, HTML body, and text body with custom field variables.

```json theme={null}
{
  "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](mailto: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](mailto: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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

<Warning>
  `unsubscribe` is a reserved custom field name. You can't use it as a custom field name.
</Warning>

1. **Case sensitivity:** Field names are case-sensitive. `{{firstName}}` and `{{FirstName}}` are different.

2. **Empty arrays:** Empty arrays don't render anything in `{{#each}}` blocks. Use `{{#if}}` to check for empty arrays.

3. **Null/undefined values:** If a nested property doesn't exist, an empty string is rendered. Use `{{#if}}` to check for existence.

4. **Data structure:** Ensure your `customFields` structure matches your template expectations. Nested objects and arrays must be valid JSON.