API reference
Templates
Versioned templates with Liquid variables.
All requests go to https://api.padimail.app with Authorization: Bearer <your key>. Try these in the interactive reference with a pm_test_ key.
Create a template
POST/v1/templates
Body
| Field | Type | Required | Notes |
|---|---|---|---|
subject | string | No | |
html | string | No | |
text | string | No | |
variables | object[] | No | Declared variables. Required ones must be given when sending. |
name | string | Yes | |
alias | string | No | A stable name to send with, like receipt. |
stream | "transactional" | "marketing" | No |
Send an Idempotency-Key header to make retries safe. The Node SDK adds one for you.
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.templates.create({
name: "Receipt",
alias: "receipt",
subject: "Your receipt #{{ order_no }}",
html: "<p>Total: {{ total }}</p>",
variables: [
{ name: "order_no", required: true },
{ name: "total", required: true },
],
});Response 200
{
"id": "tpl_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "template",
"name": "string",
"alias": "string",
"stream": "transactional",
"current_version": 0,
"created_at": "2026-10-27T13:05:09Z",
"updated_at": "2026-10-27T13:05:09Z",
"draft": {
"version": 0,
"subject": "string",
"html": "string",
"text": "string",
"variables": [
{
"name": "string",
"type": "string",
"required": false,
"sample": null
}
],
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"published_at": "2026-10-27T13:05:09Z"
},
"published": {
"version": 0,
"subject": "string",
"html": "string",
"text": "string",
"variables": [
{
"name": "string",
"type": "string",
"required": false,
"sample": null
}
],
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"published_at": "2026-10-27T13:05:09Z"
}
}List templates
GET/v1/templates
Query parameters
| Field | Type | Required | Notes |
|---|---|---|---|
limit | integer | No | Page size, 1 to 100. Default 50. |
after | string | No | Return items after this ID (the next value of the previous page). |
before | string | No | Return items before this ID. |
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.templates.list();Response 200
{
"data": [
{
"id": "tpl_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "template",
"name": "string",
"alias": "string",
"stream": "transactional",
"current_version": 0,
"created_at": "2026-10-27T13:05:09Z",
"updated_at": "2026-10-27T13:05:09Z"
}
],
"has_more": false,
"next": "string"
}Get a template
GET/v1/templates/{id}
Path parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | Yes | The template's ID (tpl_…) or alias. |
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.templates.get("receipt");Response 200
{
"id": "tpl_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "template",
"name": "string",
"alias": "string",
"stream": "transactional",
"current_version": 0,
"created_at": "2026-10-27T13:05:09Z",
"updated_at": "2026-10-27T13:05:09Z",
"draft": {
"version": 0,
"subject": "string",
"html": "string",
"text": "string",
"variables": [
{
"name": "string",
"type": "string",
"required": false,
"sample": null
}
],
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"published_at": "2026-10-27T13:05:09Z"
},
"published": {
"version": 0,
"subject": "string",
"html": "string",
"text": "string",
"variables": [
{
"name": "string",
"type": "string",
"required": false,
"sample": null
}
],
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"published_at": "2026-10-27T13:05:09Z"
}
}Update the draft
PATCH/v1/templates/{id}
Path parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | Yes | The template's ID (tpl_…) or alias. |
Body
| Field | Type | Required | Notes |
|---|---|---|---|
subject | string | No | |
html | string | No | |
text | string | No | |
variables | object[] | No | |
name | string | No | |
alias | string | null | No | |
stream | "transactional" | "marketing" | No | |
restore_version | integer | No |
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.templates.update("receipt", { subject: "Receipt for order #{{ order_no }}" });Response 200
{
"id": "tpl_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "template",
"name": "string",
"alias": "string",
"stream": "transactional",
"current_version": 0,
"created_at": "2026-10-27T13:05:09Z",
"updated_at": "2026-10-27T13:05:09Z",
"draft": {
"version": 0,
"subject": "string",
"html": "string",
"text": "string",
"variables": [
{
"name": "string",
"type": "string",
"required": false,
"sample": null
}
],
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"published_at": "2026-10-27T13:05:09Z"
},
"published": {
"version": 0,
"subject": "string",
"html": "string",
"text": "string",
"variables": [
{
"name": "string",
"type": "string",
"required": false,
"sample": null
}
],
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"published_at": "2026-10-27T13:05:09Z"
}
}Delete a template
DELETE/v1/templates/{id}
Path parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | Yes | The template's ID (tpl_…) or alias. |
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.templates.remove("receipt");Response 200
{ "id": "string", "object": "string", "deleted": true }Publish the draft as version N+1
POST/v1/templates/{id}/publish
Path parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | Yes | The template's ID (tpl_…) or alias. |
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.templates.publish("receipt");Response 200
{
"id": "tpl_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S",
"object": "template",
"name": "string",
"alias": "string",
"stream": "transactional",
"current_version": 0,
"created_at": "2026-10-27T13:05:09Z",
"updated_at": "2026-10-27T13:05:09Z",
"draft": {
"version": 0,
"subject": "string",
"html": "string",
"text": "string",
"variables": [
{
"name": "string",
"type": "string",
"required": false,
"sample": null
}
],
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"published_at": "2026-10-27T13:05:09Z"
},
"published": {
"version": 0,
"subject": "string",
"html": "string",
"text": "string",
"variables": [
{
"name": "string",
"type": "string",
"required": false,
"sample": null
}
],
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"published_at": "2026-10-27T13:05:09Z"
}
}Preview with variables
POST/v1/templates/{id}/render
Path parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | Yes | The template's ID (tpl_…) or alias. |
Body
| Field | Type | Required | Notes |
|---|---|---|---|
variables | object | No | |
version | integer | No |
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.templates.render("receipt", { variables: { order_no: "1042", total: "₦12,500" } });Response 200
{
"subject": "string",
"html": "string",
"text": "string",
"missing_variables": ["string"]
}List a template's versions
GET/v1/templates/{id}/versions
Path parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | Yes | The template's ID (tpl_…) or alias. |
Example
import { PadiMail } from "@padimail/node";
const pm = new PadiMail(process.env.PADIMAIL_API_KEY);
const result = await pm.templates.versions("receipt");Response 200
{
"data": [
{
"version": 0,
"subject": "string",
"html": "string",
"text": "string",
"variables": [
{
"name": "string",
"type": "string",
"required": false,
"sample": null
}
],
"created_by": "string",
"created_at": "2026-10-27T13:05:09Z",
"published_at": "2026-10-27T13:05:09Z"
}
]
}Was this page helpful?