POSTJECTDOCS

Templates

Create reusable email templates with dynamic variables. Postject uses Liquid.js for template rendering.

Variable Syntax

Postject uses Liquid.js as its template engine. Variables are inserted using double curly braces: {{ variable_name }}. Variables are replaced with their corresponding values at send time.

html
<html>
  <body>
    <h1>Welcome, {{ first_name }}!</h1>
    <p>Thanks for signing up for {{ product_name }}.</p>
    <p>Your account has been created with the email {{ email }}.</p>
    <a href="{{ confirmation_url }}">Confirm your email address</a>
    <p>If you did not create this account, you can safely ignore this email.</p>
  </body>
</html>

Liquid.js Features

Beyond simple variable substitution, Liquid.js supports conditionals ( {% if condition %}), loops ( {% for item in array %}), and filters ( {{ name | upcase }}). Refer to the Liquid.js documentation for the full syntax reference.

Create a Template

Creates a new email template within a server. The template can include Liquid.js variables that will be replaced with dynamic values when the email is sent. Requires JWT Bearer authentication.

POSThttps://api.postject.com/v1/templates

Request Body

serverIdstring (required)

The ID of the server this template belongs to.

namestring (required)

A descriptive name for the template (e.g., "Welcome Email").

subjectstring (required)

The email subject line. Can include Liquid.js variables.

htmlstring (required)

The HTML body of the email template with Liquid.js variables.

variablesstring[] (required)

An array of variable names used in the template. Used for validation when sending.

json
{
  "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
  "name": "Welcome Email",
  "subject": "Welcome to {{ product_name }}, {{ first_name }}!",
  "html": "<html><body><h1>Welcome, {{ first_name }}!</h1><p>Thanks for joining {{ product_name }}. We're excited to have you on board.</p><a href=\"{{ confirmation_url }}\">Confirm your email</a></body></html>",
  "variables": ["first_name", "product_name", "confirmation_url"]
}

Response

json
{
  "id": "clx9c5o3d0007xz0z2p3q4r5s",
  "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
  "name": "Welcome Email",
  "subject": "Welcome to {{ product_name }}, {{ first_name }}!",
  "html": "<html><body><h1>Welcome, {{ first_name }}!</h1><p>Thanks for joining {{ product_name }}. We're excited to have you on board.</p><a href=\"{{ confirmation_url }}\">Confirm your email</a></body></html>",
  "variables": ["first_name", "product_name", "confirmation_url"],
  "createdAt": "2025-07-16T11:00:00.000Z",
  "updatedAt": "2025-07-16T11:00:00.000Z"
}

List Templates

Returns all templates for the authenticated user's account. Requires JWT Bearer authentication.

GEThttps://api.postject.com/v1/templates
json
[
  {
    "id": "clx9c5o3d0007xz0z2p3q4r5s",
    "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
    "name": "Welcome Email",
    "subject": "Welcome to {{ product_name }}, {{ first_name }}!",
    "variables": ["first_name", "product_name", "confirmation_url"],
    "createdAt": "2025-07-16T11:00:00.000Z",
    "updatedAt": "2025-07-16T11:00:00.000Z"
  },
  {
    "id": "clx9d6p4e0008yz1z3q4r5s6t",
    "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
    "name": "Password Reset",
    "subject": "Reset your {{ product_name }} password",
    "variables": ["product_name", "reset_url", "expiry_hours"],
    "createdAt": "2025-07-16T12:30:00.000Z",
    "updatedAt": "2025-07-16T12:30:00.000Z"
  }
]

Get a Template

Retrieves a single template by its ID, including the full HTML body. Requires JWT Bearer authentication.

GEThttps://api.postject.com/v1/templates/:id
json
{
  "id": "clx9c5o3d0007xz0z2p3q4r5s",
  "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
  "name": "Welcome Email",
  "subject": "Welcome to {{ product_name }}, {{ first_name }}!",
  "html": "<html><body><h1>Welcome, {{ first_name }}!</h1><p>Thanks for joining {{ product_name }}. We're excited to have you on board.</p><a href=\"{{ confirmation_url }}\">Confirm your email</a></body></html>",
  "variables": ["first_name", "product_name", "confirmation_url"],
  "createdAt": "2025-07-16T11:00:00.000Z",
  "updatedAt": "2025-07-16T11:00:00.000Z"
}

Update a Template

Updates an existing template. All fields are optional — only the fields you include in the request body will be updated. Requires JWT Bearer authentication.

PUThttps://api.postject.com/v1/templates/:id

Request Body

namestring (optional)

The updated template name.

subjectstring (optional)

The updated subject line.

htmlstring (optional)

The updated HTML body.

variablesstring[] (optional)

The updated list of variable names.

json
{
  "subject": "Welcome aboard, {{ first_name }}!",
  "variables": ["first_name", "product_name", "confirmation_url", "trial_days"]
}

Response

json
{
  "id": "clx9c5o3d0007xz0z2p3q4r5s",
  "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
  "name": "Welcome Email",
  "subject": "Welcome aboard, {{ first_name }}!",
  "html": "<html><body><h1>Welcome, {{ first_name }}!</h1><p>Thanks for joining {{ product_name }}. We're excited to have you on board.</p><a href=\"{{ confirmation_url }}\">Confirm your email</a></body></html>",
  "variables": ["first_name", "product_name", "confirmation_url", "trial_days"],
  "createdAt": "2025-07-16T11:00:00.000Z",
  "updatedAt": "2025-07-17T09:45:00.000Z"
}

Delete a Template

Permanently deletes a template. Messages that were previously sent using this template are not affected. Requires JWT Bearer authentication.

DELETEhttps://api.postject.com/v1/templates/:id
json
{
  "message": "Template deleted successfully",
  "id": "clx9c5o3d0007xz0z2p3q4r5s"
}

Using Templates When Sending

Instead of providing inline HTML in every send request, you can reference a saved template by its ID and pass the required variables. Postject will render the template with your variables using Liquid.js before sending.

bash
curl -X POST https://api.postject.com/v1/send \
  -H "Authorization: Bearer pt_live_your_server_token" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "alice@example.com",
    "templateId": "clx9c5o3d0007xz0z2p3q4r5s",
    "variables": {
      "first_name": "Alice",
      "product_name": "Postject",
      "confirmation_url": "https://app.postject.com/confirm?token=abc123"
    }
  }'

When using a template, the subject and html fields are pulled from the template automatically. You do not need to provide them in the request body.

json
{
  "id": "msg_03ka6b0m4c5d6e7f",
  "status": "queued",
  "to": "alice@example.com",
  "subject": "Welcome to Postject, Alice!",
  "templateId": "clx9c5o3d0007xz0z2p3q4r5s"
}