---
title: "Templates & variables"
description: "Reference a saved template and pass per-recipient data."
url: https://www.unitpost.com/docs/templates
section: Docs
updated: 2026-08-28
---
# Templates & variables

## Templates & variables

> Reference a saved template and pass per-recipient data.

Rather than inlining HTML on every send, save a template once and reference it by ID. Pass `template.variables` and any {{variable}} in the template is substituted at send time.

**cURL**

```bash
curl https://www.unitpost.com/api/v1/email \
  -H "Authorization: Bearer $UNITPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-app/1.0" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "customer@acme.com",
    "template": {
      "id": "tmpl_123",
       "variables": { "plan": "Pro" }
    }
  }'
```

**Node.js**

```ts
import { Unitpost } from "unitpost";

const unitpost = new Unitpost(process.env.UNITPOST_API_KEY);

const { data, error } = await unitpost.email.send({
  from: "you@yourdomain.com",
  to: "customer@acme.com",
  template: {
    id: "tmpl_123",
    variables: { plan: "Pro" },
  },
});
```

**Python**

```python
from unitpost import Unitpost

unitpost = Unitpost()

result = unitpost.email.send({
    "from": "you@yourdomain.com",
    "to": "customer@acme.com",
    "template": {
        "id": "tmpl_123",
        "variables": {"plan": "Pro"},
    },
})
```

**Ruby**

```ruby
require "unitpost"

unitpost = Unitpost::Client.new

result = unitpost.email.send({
  from: "you@yourdomain.com",
  to: "customer@acme.com",
  template: {
    id: "tmpl_123",
    variables: { plan: "Pro" },
  },
})
```

**PHP**

```php
require 'vendor/autoload.php';

use Unitpost\Client;

$unitpost = new Client(); // reads UNITPOST_API_KEY

$result = $unitpost->email->send([
    "from" => "you@yourdomain.com",
    "to" => "customer@acme.com",
    "template" => [
        "id" => "tmpl_123",
        "variables" => ["plan" => "Pro"],
    ],
]);
```

**Laravel**

```php
use Unitpost\Laravel\Facades\Unitpost;

$result = Unitpost::email()->send([
    "from" => "you@yourdomain.com",
    "to" => "customer@acme.com",
    "template" => [
        "id" => "tmpl_123",
        "variables" => ["plan" => "Pro"],
    ],
]);
```

**Go**

```go
import (
    "context"
    "github.com/unitpostcom/unitpost-go"
)

client := unitpost.New() // reads UNITPOST_API_KEY

data, err := client.Email.Send(ctx, map[string]any{
	"from": "you@yourdomain.com",
	"to":   "customer@acme.com",
	"template": map[string]any{
		"id":        "tmpl_123",
		"variables": map[string]any{"plan": "Pro"},
	},
})
```

**Java**

```java
import com.unitpost.Unitpost;

var unitpost = new Unitpost(); // reads UNITPOST_API_KEY

var result = unitpost.email.send(java.util.Map.of(
    "from", "you@yourdomain.com",
    "to", "customer@acme.com",
    "template", java.util.Map.of(
        "id", "tmpl_123",
        "variables", java.util.Map.of("plan", "Pro")
    )
));
```

**Rust**

```rust
use unitpost::Unitpost;

let unitpost = Unitpost::new(); // reads UNITPOST_API_KEY

let result = unitpost.email().send(serde_json::json!({
    "from": "you@yourdomain.com",
    "to": "customer@acme.com",
    "template": {
        "id": "tmpl_123",
        "variables": {"plan": "Pro"}
    }
})).await;
```

**.NET**

```csharp
using Unitpost;

var unitpost = new UnitpostClient(); // reads UNITPOST_API_KEY

var result = await unitpost.Email.Send(new
{
    from = "you@yourdomain.com",
    to = "customer@acme.com",
    template = new
    {
        id = "tmpl_123",
        variables = new { plan = "Pro" },
    },
});
```

When you send to a known contact, that contact's custom fields merge into the variables automatically — so a template can reference {{first_name}} without you re-sending it on every request.

> **Drafts can't be sent:** A template must be published before the API will send it. Referencing a draft returns a 422 with code template_not_published. Publish it in the editor first.

Author templates in the visual editor, or in your app with `import { Heading, render } from "@unitpost/email/react"` and POST `{ name, html: render(<Email />), subject }`. Manage them under Templates (/dashboard/email/templates). Every block and layout is documented at /components (/components).

## Related

- [Subscription topics](https://www.unitpost.com/docs/topics): Let contacts opt out of one kind of mail without leaving your list.
- [Sending domains](https://www.unitpost.com/docs/domains): Add SPF, DKIM, and DMARC so mail sends from your domain.
- [Open & click tracking](https://www.unitpost.com/docs/tracking): Control engagement tracking per send, template, or category.