API Reference

Templates

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.

Overview

MethodPathDescription
GET/api/v1/templatesYour templates, newest first, without their email.
GET/api/v1/templates/{id}One template, with its email as written.
POST/api/v1/templatesCreate 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).

Create a template

POST/api/v1/templates

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.

FieldTypeDescription
namestringWhat your team calls it in Templates, up to 200 characters. Left out: its subject, else "Untitled Template".
subjectstringThe subject line. With a starter, the starter's when left out.
preview_textstringThe line an inbox shows after the subject.
designobjectThe email as a design in PristineSend's design format (GET /design-kit has it as design_format).
starterstringOne of the four starters: launch, sale, newsletter or welcome, on your brand when your brand kit is set.
markdownstringA plain email in Markdown, as the Simple editor writes. HTML tags show as text.
htmlstringThe 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.

import { PristineSend } from "pristinesend"

const ps = new PristineSend(process.env.PRISTINESEND_API_KEY!)

// An email another tool exported: its pictures are copied into your library.
const { data: template, check, pictures_copied } = await ps.templates.create({
  name: "Spring sale",
  subject: "Spring is here",
  preview_text: "20% off everything this weekend",
  html: exportedHtml,
})

console.log(template.app_url, pictures_copied.length, check.deliverability.score)

HTML and its pictures

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.

List and read

GET/api/v1/templates

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.

GET/api/v1/templates/{id}
FieldTypeDescription
idstring (uuid)Pass it as template_id to POST /campaigns.
namestringWhat your team calls it in Templates.
subjectstringAs written; empty while it has no subject.
preview_textstringThe line an inbox shows after the subject. Not in the list.
formatstringdesign, markdown or html: how it is built.
design / markdown / htmlobject | string | nullThe 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.
versionnumberName it when you change the template. Raised on every change to the name, subject, preview text or email, whoever makes it.
app_urlstringWhere it opens in PristineSend.
created_at / updated_atstringWhen it was made, and last changed.

Change a template

PATCH/api/v1/templates/{id}

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.

const current = await ps.templates.get(templateId)

const { data } = await ps.templates.update(templateId, {
  version: current.version,
  subject: "Spring is here: 20% off",
})

Start a draft from a template

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.

const { data: draft } = await ps.campaigns.create({
  template_id: templateId,
  subject: "Spring is here, Alex",
})
// Nothing is sent: give a person draft.app_url to check and send it.

Errors

StatuscodeWhen
400missing_fieldNo email was given on create, or no version on a change.
400invalid_fieldA 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).
400invalid_requestThe body is not a JSON object, or a change names nothing to change.
401unauthorizedMissing or invalid API key.
403insufficient_scopeThe key lacks campaigns:read (reading) or campaigns:write (writing).
404not_foundThis account has no template with that id.
409conflictThe template changed after the version you read: read it again and redo your change.
429rate_limited60 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.
503service_unavailableA 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.