A template is where a campaign starts. Make one from a design, a starter, Markdown, or HTML another tool exported, and start a campaign draft from it. Nothing here sends anything.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/templates | Your templates, newest first, without their email. |
GET | /api/v1/templates/{id} | One template, with its email as written. |
POST | /api/v1/templates | Create a template from a design, a starter, Markdown or HTML. |
PATCH | /api/v1/templates/{id} | Change a template at the version you read. |
Reading needs the campaigns:read scope, writing campaigns:write, the same as drafts: a template sends nothing, as a draft sends nothing. Drafts and templates share one limit: 60 saves a minute per account. Send an Idempotency-Key on a create, so a retried request cannot make a second template. Through MCP, your AI has list_templates, get_template and save_template (MCP).
Give the email exactly one way: design, starter, markdown or html. A design or Markdown may show only pictures from your picture library or PristineSend's built-in backgrounds, as a draft may: add a picture first with POST /api/v1/pictures. A field the request does not take is refused, never ignored.
| Field | Type | Description |
|---|---|---|
name | string | What your team calls it in Templates, up to 200 characters. Left out: its subject, else "Untitled Template". |
subject | string | The subject line. With a starter, the starter's when left out. |
preview_text | string | The line an inbox shows after the subject. |
design | object | The email as a design in PristineSend's design format (GET /design-kit has it as design_format). |
starter | string | One of the four starters: launch, sale, newsletter or welcome, on your brand when your brand kit is set. |
markdown | string | A plain email in Markdown, as the Simple editor writes. HTML tags show as text. |
html | string | The whole email as HTML, up to 2 MB, as another tool exported it. See below for its pictures. |
The answer is 201 with the template as stored, its check (the deliverability score, design findings and warnings, as a draft's save answers) and pictures_copied.
Tools that export an email usually keep its pictures on their own servers. When you give html, every picture the email shows from another site (an <img>, an Outlook picture, a background in a style) is copied into your picture library and the HTML is pointed at the copy, so the email no longer depends on that tool's servers, and they no longer see when it is opened. Each copy is checked as an upload is: the address must be public, the bytes must be a JPEG, PNG, WebP or GIF, and the picture is made the size an email needs.
Left as they are: pictures already in your library, the built-in backgrounds, placeholders and anything that is not a web address (the check reports those). A picture whose address comes from a merge tag is refused. A picture that cannot be copied refuses the request, naming it and saying why. One request copies at most 60 pictures, and your account may copy 30 a minute and 300 a day, as POST /api/v1/pictures does.
A picture copied before from the same address is used again without opening it or counting it. So when a request is refused because the minute's copies ran out (429), or answered 503 because it ran out of time, send the same request again: each try copies on from where the last one got to. Pictures copied before a refusal stay in your library, where your team sees them and can remove them.
Newest first, limit 1 to 100 (default 50), and cursor from the previous page's next_cursor (Pagination). The list leaves out each template's email; read one for it.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Pass it as template_id to POST /campaigns. |
name | string | What your team calls it in Templates. |
subject | string | As written; empty while it has no subject. |
preview_text | string | The line an inbox shows after the subject. Not in the list. |
format | string | design, markdown or html: how it is built. |
design / markdown / html | object | string | null | The email as written, the one its format names; the others are null. A designed template answers its design, never the HTML it renders to. Not in the list. |
version | number | Name it when you change the template. Raised on every change to the name, subject, preview text or email, whoever makes it. |
app_url | string | Where it opens in PristineSend. |
created_at / updated_at | string | When it was made, and last changed. |
Name the version you read, and send only what changes: name, subject, preview_text, and at most one of design, edits (changes by part id, for a designed template, as a draft takes them), markdown and html. A template changed since that version, in PristineSend or by anyone else, is refused with 409 conflict and never overwritten: read it again and redo your change.
POST /api/v1/campaigns takes a template_id as its email, as New campaign's templates door does: the draft gets the template's subject, preview text and email, and a subject or preview_text you give replaces the template's. Changing the draft later never changes the template.
| Status | code | When |
|---|---|---|
400 | missing_field | No email was given on create, or no version on a change. |
400 | invalid_field | A field the request does not take, a design that does not validate (param names the part), a picture outside your library in a design or Markdown, or a picture in the HTML that could not be copied (the message names it and says why). |
400 | invalid_request | The body is not a JSON object, or a change names nothing to change. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_scope | The key lacks campaigns:read (reading) or campaigns:write (writing). |
404 | not_found | This account has no template with that id. |
409 | conflict | The template changed after the version you read: read it again and redo your change. |
429 | rate_limited | 60 draft and template saves a minute per account, or the account's 30 pictures copied a minute. Retry after Retry-After: the pictures copied so far are used again. |
503 | service_unavailable | A read or write behind the save failed, or the pictures took longer than one request may: send the same request again. |
See Error codes for the envelope and the full list.