Make and edit campaign drafts from your own code or your own AI: from a design, one of our starters, or Markdown. Nothing here sends anything.
A draft made here is a draft like any other. It opens in the PristineSend editor at its app_url, where anyone on the team can change it by hand, and a person sends it from there. Everything that runs before a campaign goes out runs as it always does.
Creating and changing a draft require campaigns:write; reading one requires campaigns:read. An account makes at most 60 draft saves a minute, beside the 1,000 requests a minute every key has; past it the answer is 429 rate_limited with a Retry-After. An account still under review, rejected or suspended cannot make drafts.
A draft is written in one of three ways: a design in the format PristineSend's Design editor uses (a theme and up to 12 sections of blocks, with no HTML or CSS anywhere in it; CampaignDesign in the OpenAPI spec), one of our four starters, or Markdown for a short plain email. Raw HTML is not taken: building with HTML stays a tool for a person in the editor.
The Markdown is the one the editor's Simple box saves, and the box shows it as the email will look. A backslash before a character that would be formatting shows the character as it is: \* is an asterisk, and \# at the start of a line is not a heading.
The email comes back as it is written: design when format is design, markdown when it is markdown. Never the HTML a design renders to, which is many times longer. A campaign built with HTML in the editor has format: "html" and neither. created_via says how it was made (app, api or agent), and open_notes lists the notes a person left on it for their AI that nobody has resolved. People leave notes in the editor, on a section or block of a design or on the whole email. A note names its part by target_id and target_type (both null for the whole email), and unanchored is true once that part was removed or became another kind of part, so the note no longer points at anything in the design.
POST /api/v1/campaigns with exactly one of design, starter, markdown and template_id, and any of subject, preview_text, sender_id and topic_id. It answers 201 with the draft and its check.
A starter is launch, sale, newsletter or welcome, as the account sees it in the editor: on brand when its brand kit is set. Its subject and preview text are used when you give none. Its buttons have no links yet, so the check says to finish them.
A template_id is one of the account's templates, as New campaign's templates door starts a draft: its subject, preview text and email, and a subject or preview_text given here replaces the template's. A template built with HTML makes a draft built with HTML, which the API reads and changes only in its subject, preview text, sender and topic, or by replacing its email with a design or Markdown.
A sender or topic must be the account's own; leave sender_id out for the account's default sender. Send an Idempotency-Key (the SDK sends one for you), so a retried request answers with the draft it made rather than making a second. Unknown fields are refused rather than ignored, so a misspelt field never looks like it took.
GET /api/v1/campaigns/{id} — any campaign of the account, draft or not, as the object above. Find drafts with GET /api/v1/campaigns?status=draft.
PATCH /api/v1/campaigns/{id} with the version you read, and what to change: any of subject, preview_text, sender_id and topic_id, and at most one of a whole design, edits and markdown. A field you leave out is not changed. Sending markdown for a designed draft replaces the design.
A change made since you read the draft is never overwritten. PristineSend raises the version on every change to a draft's email, sender or topic, whoever makes it: a person in the editor, another key, another AI. If the draft is no longer at the version you name, the answer is 409 conflict and nothing changes; read it again and make your change on what it holds now. A campaign that is no longer a draft cannot be changed at all, also 409.
An Idempotency-Key is optional here (the SDK sends one). With it, a retry whose first answer was lost replays that answer, instead of meeting its own change as a newer version.
Every section, block and column in a design has an id. edits is a list of up to 50 changes, applied in order, each naming the part it changes, so you can change one heading without sending the whole email again. A part you add may leave out its id; it is given a new one. Each edit is checked as it is applied, and a problem is reported at the edit that caused it (param edits[1].fields.text).
| op | Takes | Does |
|---|---|---|
update | id, fields | Replace fields of the block or section with this id. Its id and type, and a section's blocks, cannot change this way. |
theme | fields | Replace fields of the theme (font, colours, corners). |
insert_block | after, block | Add a block after the block with this id, or at the end of the section with this id. |
insert_section | after, section | Add a section after the section with this id, or at the end when after is null or left out. |
move | id, direction | Move a section or block one place "up" or "down" among its neighbours. |
duplicate | id | Copy a section or block, with new ids, right after it. |
remove | id | Remove a section or block. An email keeps at least one section, and a section at least one block. |
Every create and change answers with check beside data, so you see what to finish without asking again. deliverability is the score the editor shows, in the shape of the deliverability check: its DANGER verdict is exactly what holds a send (an empty picture spot, a placeholder link or picture, no subject). design_issues names the parts of a design to look at again: text or a button that is hard to read on its colour, a button with no link, a picture spot still empty. warnings says what the save could not do as asked.
POST /api/v1/campaigns/{id}/check — the check a save answers with, for any campaign of the account, whenever you want it again (after a person edits the draft, say). With {"links": true}, PristineSend opens every link and picture in the email, as the review page does: a link that does not open and a picture that does not load join the score, and links says what was found and what could not be checked. It writes nothing, and requires campaigns:read.
Broken is said only when the answer is unambiguous: the site does not exist, the page answers “not found”, or a picture's address is not a picture. A login wall, a slow server or a bot blocker is unchecked, never broken. Unsubscribe links are never opened, so the check unsubscribes nobody, and an address filled in for each recipient cannot be checked ahead (both are in skipped).
Opening links takes one per address from the account's 150 a minute, shared with the editor and the review page; past it the answer is 429 rate_limited with a Retry-After. One check opens at most 30 addresses, and not_checked counts the rest.
POST /api/v1/campaigns/{id}/test sends the campaign as a test, exactly as the editor's Send test does: merge tags filled for a sample contact, the subject marked [TEST], and unsubscribe links that say nothing was changed. It goes only to someone on the account's team: to must be the address a team member signs in with. Through a connected AI, leave to out and the test goes to the person who connected it; an API key must name to. It never sends the campaign itself.
It requires campaigns:write and is refused for the same reasons as the editor's test: an account not approved, a sending domain not verified, a sender whose domain lost its verification, an address on the do-not-send list. At most 100 tests a day per account, shared with the editor; past it the answer is 429 rate_limited with a Retry-After saying when the next one is free. A ps_test_ key's test is captured, not delivered. Send an Idempotency-Key (the SDK sends one), so a retry never sends a second test.
People leave notes for their AI in the editor, and a draft's open_notes lists the ones nobody has resolved. Change the draft for a note first, then POST /api/v1/campaigns/{id}/notes/{note_id}/resolve with a short reply (up to 500 characters) saying what you changed. The person reads the reply beside their note, with who answered: a connected AI by the person who connected it, an API key by its name. A note you could not do is best left open, with the reason told to the person.
It requires campaigns:write, and works on drafts only: a campaign that is no longer a draft answers 409 conflict. Resolving changes nothing in the email and sends nothing. A note already resolved, by an earlier try whose answer was lost or by someone else first, comes back as it stands, with who resolved it, and is never written over, so a retry is safe without an Idempotency-Key. A person can reopen a note in the editor, and it is open again in the draft's open_notes.
GET /api/v1/design-kit — everything your AI needs to design an email for this account, in one read: the brand kit (colours, font, corners, logo, website, and the voice and rules written in Settings → Brand), the picture library and the built-in backgrounds (the only pictures a draft may show), the four starters as this account sees them, the design format itself as one JSON Schema document (design_format), the senders, topics and merge tags a draft may use, and the rules: the design format's limits and every rule of the deliverability score, with whether it holds a send. It requires campaigns:read.
A picture's description was written for its alt text: null means nobody has described it yet, and an empty one means it is decorative. A section that shows a background picture takes the background's fallback_color as its colour and its text_color for text: mail that blocks pictures shows only the colour. The kit lists the newest 50 pictures; pictures_more says when there are more.
A draft made through the API shows only pictures from the account's picture library and PristineSend's built-in backgrounds, so nobody's code places a stranger's picture, a tracking pixel or a stock photo in the account's email without it being in the library first, where the team sees it. To show a picture from somewhere else, such as a product photo on the account's own website, add it to the library and put the address it answers in the image block. Or leave the spot for a person to fill (an image block with image: null). A picture already in the draft, put there by a person in the editor, stays allowed. A picture's address cannot come from a merge tag.
Every picture downloads when the email is opened, so the check weighs them from the sizes the library keeps (each picture in the design kit lists its bytes): each picture of 1 MB or more is flagged and costs 5 points of its own, up to 15, and pictures that would still add up to 2 MB once the heavy ones were 500 KB are flagged as too many. Neither holds a send. Pictures uploaded in PristineSend, or added by address, are made the size an email needs, at most 1,200px wide, with photos saved as JPEG.
POST /api/v1/pictures copies the picture at a web address into the account's picture library: url, the address of the picture itself (not of a page it is on), and optionally description, what it shows for readers who cannot see it ("" for a decorative picture). It requires campaigns:write, and it sends nothing.
The address is opened from PristineSend's servers, never on a private network, with every redirect checked, and at most 10 MB is read in 12 seconds. What arrives must be a JPEG, PNG, WebP or GIF, whatever the site says it is. It is then made the size an email needs, as an upload is: at most 1,200px wide, a photo saved as JPEG, its metadata (a phone's location, say) removed, a WebP never kept, because classic Outlook cannot show one, and a GIF kept as it came, to keep its animation. A picture still over 4 MB after that is refused.
The answer is 201 with the library's picture: put its url in an image block. When the library already shows a picture with the same bytes, that picture is answered instead of a copy, with 200, reused: true and its own description. The library shows the picture as copied from that address, and anyone on the team removes it there like any other.
An account adds at most 30 pictures a minute and 300 a day this way. An address that gave no picture is 400 invalid_field with param: "url" and what happened (no picture there, a site that refused, a picture too large). An Idempotency-Key is optional: with one, a retry whose first answer was lost replays it. A refusal that may end by itself (the site timed out, could not be reached, or answered 429 or 5xx) is not kept under the key, so a retry opens the address again.
400 invalid_field names the field in param, down to the part of a design (design.sections[2].blocks[0].label), with the rule in words. 404 not_found is a campaign this account does not have, whoever's it is, or a note that campaign does not have. 409 conflict is a draft that changed since you read it, or a campaign that is no longer a draft (and, for a test, open tracking set to off where it is not available). 429 rate_limited is a limit used up, with a Retry-After. 502 provider_error is a test the email provider refused. 503 service_unavailable means a read or write behind it failed; retry. See Errors.