Mailneo
|Docs

Templates

Templates API

5 endpoints under https://api.mailneo.co/api/v2. Every request carries your key in the x-api-key header.

Scopes used on this page: templates:read, templates:write. Each endpoint below states the one it requires. Start with the quickstart →

GET/templates

List templates

Requires templates:read

Cursor-paginated. Pass updated_since with the synced_through value from your previous run to fetch only what changed; you will occasionally re-see a row, so upsert by id. Deletes are not visible to updated_since. The template body is not included here — fetch a single template to get it.

Query parameters7
limitintegerdefault: 251..100
cursorstring≤ 256 chars
Opaque page cursor from a previous response’s next_cursor. Treat it as a black box: cursors are bound to the sort they were issued under and are validated strictly, so a hand-crafted, modified or foreign cursor — including any cursor issued before the 2026-08 format revision — answers 400 cursor_invalid. On that error, restart from the first page.
order"asc" | "desc"default: desc
updated_sincestring · date-time
sort"updated_at" | "created_at"default: updated_at
categorystring≤ 50 chars
searchstring≤ 200 chars
curl "https://api.mailneo.co/api/v2/templates?limit=25&order=desc&sort=updated_at" \
  -H "x-api-key: $MAILNEO_API_KEY"
{
  "data": [
    {
      "object": "template",
      "id": "c0c9y51n0bzyjco0ctxcfl0cj",
      "name": "Welcome email",
      "description": "Created via the API.",
      "subject": "April product notes",
      "category": "…",
      "created_at": "2026-05-11T09:30:00.000Z",
      "updated_at": "2026-06-24T15:45:00.000Z"
    }
  ],
  "meta": {
    "request_id": "6a269ce8-6b26-4e7b-ac26-a00e6d26a1a1",
    "has_more": false,
    "next_cursor": null,
    "synced_through": "2026-06-24T15:45:00.000Z"
  }
}
POST/templates

Create a template

Requires templates:write · Idempotency-Key optional

Creates one template. name must be unique within the team — a duplicate is a 409 resource_already_exists, not a silent second copy. Templates are private to the team that owns them; there is no way to publish one, and no request field controls visibility.

Query parameters1
dry_runboolean
Report what this call WOULD do and commit nothing. Returns data: null and a meta.impact block. Requires the resource's :read scope in addition to the scope this endpoint declares. Must be exactly true or false.
Header parameters1
Idempotency-Keystring≤ 255 chars
A caller-chosen unique string, at most 255 characters. Retrying with the same key replays the first response instead of repeating the work; the replay carries Idempotent-Replayed: true. Reusing a key with a different body is a 409 idempotency_key_reused. Keys are remembered for 24 hours.
Body parameters5
namestringrequired1..100 chars
subjectstringrequired1..200 chars
bodystringrequired1..524288 chars
descriptionstring · nullable≤ 500 chars
categorystring · nullable≤ 50 chars
curl -X POST "https://api.mailneo.co/api/v2/templates" \
  -H "x-api-key: $MAILNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "subject": "April product notes",
    "body": "<p>Hi {{first_name}},</p>",
    "description": "Created via the API.",
    "category": "…"
  }'
{
  "data": "…",
  "meta": {
    "request_id": "aac7b41d-a9c7-428a-a8c7-b0f7a7c7af64",
    "dry_run": false
  }
}
GET/templates/{templateId}

Retrieve a template

Requires templates:read

Returns the full template, including the body omitted from the list response.

Path parameters1
templateIdstringrequired1..64 chars
curl "https://api.mailneo.co/api/v2/templates/{templateId}" \
  -H "x-api-key: $MAILNEO_API_KEY"
{
  "data": {
    "object": "template",
    "id": "c0c9y51n0bzyjco0ctxcfl0cj",
    "name": "Welcome email",
    "description": "Created via the API.",
    "subject": "April product notes",
    "category": "…",
    "created_at": "2026-05-11T09:30:00.000Z",
    "updated_at": "2026-06-24T15:45:00.000Z",
    "body": "<p>Hi {{first_name}},</p>"
  },
  "meta": {
    "request_id": "66d3e185-65d3-4ff2-a4d3-de5f63d3dccc"
  }
}
PATCH/templates/{templateId}

Update a template

Requires templates:write · Idempotency-Key optional

Merge-patch: fields you omit are left alone, and null clears description or category. name, subject and body cannot be cleared — they are required columns — so sending null for one is a 400. Renaming to a name another template in the team already uses is a 409.

Path parameters1
templateIdstringrequired1..64 chars
Query parameters1
dry_runboolean
Report what this call WOULD do and commit nothing. Returns data: null and a meta.impact block. Requires the resource's :read scope in addition to the scope this endpoint declares. Must be exactly true or false.
Header parameters1
Idempotency-Keystring≤ 255 chars
A caller-chosen unique string, at most 255 characters. Retrying with the same key replays the first response instead of repeating the work; the replay carries Idempotent-Replayed: true. Reusing a key with a different body is a 409 idempotency_key_reused. Keys are remembered for 24 hours.
Body parameters5
namestring1..100 chars
subjectstring1..200 chars
bodystring1..524288 chars
descriptionstring · nullable≤ 500 chars
categorystring · nullable≤ 50 chars
curl -X PATCH "https://api.mailneo.co/api/v2/templates/{templateId}" \
  -H "x-api-key: $MAILNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "subject": "April product notes",
    "body": "<p>Hi {{first_name}},</p>",
    "description": "Created via the API.",
    "category": "…"
  }'
{
  "data": "…",
  "meta": {
    "request_id": "5f0ecd2c-600e-4ebf-a10e-d052620ed1e5",
    "dry_run": false
  }
}
DELETE/templates/{templateId}

Delete a template

Requires templates:write

Permanent, and there is no undo — call with ?dry_run=true first. Campaign steps that were built from this template keep their own copy of the subject and body and are unaffected. An automation "send email" step that references the template by id is NOT protected by a foreign key: deleting the template leaves that step with a dangling reference, and it will fail when the automation next runs. Check your automations before deleting a template they use.

Path parameters1
templateIdstringrequired1..64 chars
Query parameters1
dry_runboolean
Report what this call WOULD do and commit nothing. Returns data: null and a meta.impact block. Requires the resource's :read scope in addition to the scope this endpoint declares. Must be exactly true or false.
curl -X DELETE "https://api.mailneo.co/api/v2/templates/{templateId}" \
  -H "x-api-key: $MAILNEO_API_KEY"
{
  "data": {
    "object": "template",
    "id": "c0c9y51n0bzyjco0ctxcfl0cj",
    "deleted": true
  },
  "meta": {
    "request_id": "68b42f52-69b4-40e5-a6b4-2c2c67b42dbf",
    "dry_run": false
  }
}