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 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" }
}
}'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. Variables also work in the subject and in the From name: "{{company_name}} Team <hi@yourdomain.com>". A variable with no value fails the send instead of going out as written.
A custom field can carry a default (set it under Contacts → Custom fields, or as default_value on the contact-fields API). A field's default is the value used for any contact that has none: when an email is sent, so {{plan}} renders it, and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once.
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.
Marketing templates go to a contact
A template in the marketing category sends to one recipient (no cc or bcc), because its unsubscribe link and List-Unsubscribe header belong to that person. If the address isn't a contact yet, the send adds it to Contacts first, so the recipient can opt out and you can find and segment them later. On the Free plan the new contact counts toward your contact limit; at the limit the send is refused with a limit error instead. An address that already unsubscribed or reported spam is added as unsubscribed, and the email is suppressed. Transactional templates never create contacts.
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. Every block and layout is documented at /components.