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

# Variables & Merge Tags

> Make every email feel personal. Put names, dates, links, and any data inside your templates.

# Variables & Merge Tags 🪄

Variables are placeholders in your template that get replaced with real data when you send the email. You write `{{first_name}}` in the template, and when the email goes out to Alex, they see "Alex."

***

## How to write a variable

Double curly braces. That's it:

```html theme={null}
<h1>Hello, {{first_name}}!</h1>
<p>Your {{plan_name}} subscription renews on {{renewal_date}}.</p>
```

When you send through the API, pass the values in the `variables` object and they'll be swapped in automatically.

***

## What if a variable is missing?

Sometimes you don't have a first name for every contact. Instead of getting a blank space, you can set a fallback with a pipe `|`:

```html theme={null}
<p>Hey {{first_name | there}},</p>
```

* If `first_name` = `"Sarah"` → renders as: **Hey Sarah,**
* If `first_name` is missing or empty → renders as: **Hey there,**

Never leave your emails looking awkward when data is missing. Always use fallbacks!

***

## Variables Mailofly adds automatically

These are always available — you don't need to pass them yourself:

| Variable | What it is |
| :- | :- |
| `{{email}}` | The recipient's email address |
| `{{unsubscribe_url}}` | A unique link for this recipient to unsubscribe |
| `{{current_year}}` | The current year (like `2026`) — useful in footers |
| `{{organization_name}}` | Your Mailofly organization name |

***

## Nested data

You can pass objects and access nested fields using dot notation:

```html theme={null}
<p>Shipping to: {{order.shipping_address.city}}, {{order.shipping_address.country}}</p>
```

In your API request, pass the nested object:

```json theme={null}
{
  "variables": {
    "order": {
      "shipping_address": {
        "city": "New York",
        "country": "USA"
      }
    }
  }
}
```

Perfect for order confirmations, shipping updates, or anything with structured data.

## Discover a saved template's variables

Every saved template exposes `variable_names`, a read-only list maintained automatically from its content. For example, `{{first_name}}` and `{{reset_url}}` produce `["first_name", "reset_url"]`. The list stays current when placeholders are added or removed, including changes made through the API or visual editor.

Retrieve only the names with `GET /templates/{id}/variables`, or `mailofly.templates.variables(id)` in the TypeScript SDK. Send actual values through `variables` as usual; `variable_names` describes the template and does not store recipient values.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.