API reference

query · string

The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.

query · 1 | 7 | 30 | 90 | 365

The period: the last 1, 7, 30, 90 or 365 days, 1 for the last 24 hours. Default: 30.

query · string

A custom period's first day instead of days, YYYY-MM-DD in timeZone, with to: up to 365 days, both included

query · string

A custom period's last day, YYYY-MM-DD in timeZone, today at the latest

query · string

IANA time zone for days and hours, e.g. Europe/Paris. Default: UTC.

path · string

The newsletter's ID or slug

body · string

The newsletter's name, shown in emails and on the archive

body · string

Lowercase letters, digits and dashes. Default: made from the name, numbered when another newsletter has it.

body · string

Square logo, 128×128 or larger: an https:// link

body · string

Name in the From field

body · string

An address on a domain added to this account (list_domains). It sends once the domain is verified.

body · string

Printed in the footer of every email. Without one, sending waits for it.

body · boolean

A public page for each sent issue, with a signup form. On for new newsletters: the website goes live after the first issue.

body · string

One sentence under the name on the archive, 200 characters at most

body · object

The archive's author page; the author's name is fromName

body · string

Under the author's name on the archive, 160 characters at most

body · string

Author photo: an https:// link. The newsletter image otherwise.

body · string[]

https:// links shown on the archive, 8 at most

body · object

Analytics tools on the newsletter's website: each loads on every page of it, never in emails, and hears of each signup there (sign_up for Google Analytics and in Tag Manager's data layer, CompleteRegistration for the Meta pixel). Pasted code keeps only its ID.

body · string

Google Analytics 4's measurement ID, like G-XXXXXXXXXX, or the code Google gives to paste. Empty removes it.

body · string

Google Tag Manager's container ID, like GTM-XXXXXXX, or its code. On the archive domain, only Google's own tags in the container run; on the newsletter's own domain (set_website_domain), all of them.

body · string

The Meta pixel's ID, the digits under its name in Meta Events Manager, or its code.

body · string

HTML for the head of every page of the newsletter's website, like another tool's code: <script>, <style>, <link> and <noscript> tags, with https:// addresses. It runs on the newsletter's own domain only (set_website_domain), never on its address on the archive domain, which other newsletters share. Code that wouldn't work is refused with the line to fix: a tag that isn't closed, text outside a tag, a JavaScript error, a meta tag, an event handler attribute, or Google Analytics, Tag Manager or Meta pixel code, which goes in analytics. Empty removes it.

body · boolean

Confirmed opt-in: new signups get an email with a button and only join once they click it. On for new newsletters. New subscribers get the confirmation email or the welcome email: turning it on while the welcome email is on needs welcome.enabled false in the same request.

body · object

List cleanup at each send: contacts who ignored several issues get a last-chance email instead (lastChance), and become dormant if they don't answer

body · boolean

On for new newsletters

body · number | null

Ignored issues in a row before the last-chance email, 2 to 100. Default 6.

body · number | null

Days without an open, click or signup, 30 to 3650. Default 180.

body · object

Email sent to each new subscriber, while signups don't need confirming: turning it on while requireConfirmation is on needs requireConfirmation false in the same request.

body · boolean

body · string

body · string

body · "rich" | "markdown"

With content: rich or markdown, the default

body · string

The email's body. Merge tags work as in campaigns. rich is an HTML fragment as the dashboard's editor writes it, as update_campaign's format describes, sections aside; markdown is Markdown.

body · string

Markdown: the same as content with format markdown

body · object

The confirmation email for confirmed opt-in. Sent back unchanged, the built-in one stays built-in and follows the name and description.

body · string

body · string

body · "rich" | "markdown"

With content: rich or markdown, the default

body · string

The email's body. It keeps its button, a link to {{confirm_url}}: <div data-button=""><a href="{{confirm_url}}">Its text</a></div>, or the same <a> in Markdown. Merge tags work as in campaigns. rich is an HTML fragment as the dashboard's editor writes it, as update_campaign's format describes, sections aside; markdown is Markdown.

body · string

Markdown: the same as content with format markdown

body · object

The list cleanup's last-chance email, which contacts who stopped opening get instead of an issue: a click on its button keeps them. Write your own to say it in your words or your readers' language. Sent back unchanged, the built-in one stays built-in and follows the name.

body · string

body · string

body · "rich" | "markdown"

With content: rich or markdown, the default

body · string

The email's body. It keeps its button, a link to {{keep_url}}: <div data-button=""><a href="{{keep_url}}">Its text</a></div>, or the same <a> in Markdown. Merge tags work as in campaigns. rich is an HTML fragment as the dashboard's editor writes it, as update_campaign's format describes, sections aside; markdown is Markdown.

body · string

Markdown: the same as content with format markdown

body · object

The signup form for the newsletter's own site. get_signup_form gives the code to paste.

body · boolean

Off for new newsletters

body · "inline" | "card"

inline, the fields and button alone; card, in a box under a headline and a line of text

body · string | null

The card's headline. null: the newsletter's name, as it changes. Empty: no headline.

body · string | null

The line under the card's headline. null: the newsletter's description, as it changes. Empty: no line.

body · boolean

Asks for a first name above the email, optional for readers. Off by default.

body · string

Default: Subscribe

body · string

Default: you@example.com

body · string[]

Sites where browsers show the form, like example.com, which covers its subdomains. Empty: any site. With sites listed, only the script form takes signups: the plain HTML form can't prove which site it's on.

body · object

Its look on its website and in its emails: a preset from list_themes and what's changed on top of it. Send only what changes; null takes a choice back to the preset's.

body · "postroom" | "broadsheet" | "garden" | "midnight" | "poster" | "swiss" | "typewriter" | "sunset"

A preset from list_themes. Another preset starts over from it: the changes made to the one before go, unless this call sends new ones.

body · object | null

Its colors in light mode, which its website shows readers whose device is in light mode or who picked Light, and its emails are written in. Hex colors. null takes one back to the preset's; the other shades derive from these three.

body · object | null

Its colors in dark mode, for readers in dark mode: on its website, and in its emails in mail apps that follow it, like Apple Mail and Outlook. An accent changed in one mode only follows into the other, lighter or darker where its page needs it. Hex colors. null takes one back to the preset's; the other shades derive from these three.

body · object | null

Fonts from list_themes. Mail clients without web fonts, like Gmail, show a close system font.

body · integer | null

Fonts with fewer weights use their closest

body · string | null

Corners of buttons, cards and pictures

body · string | null

Cards and forms on the website. Emails have none.

body · string | null

Line height and space between paragraphs

body · string | null

Emails only: where they sit on a screen wider than them, like a computer's. center, or left like a personal email. Phones show them full width either way.

path · string

The newsletter's ID or slug

body · string

The newsletter's name, shown in emails and on the archive

body · string

Lowercase letters, digits and dashes, not a name Postroom keeps like www, api or mail. The website's address on the archive domain follows it.

body · string

Square logo, 128×128 or larger: an https:// link

body · string

Name in the From field

body · string

An address on a domain added to this account (list_domains). It sends once the domain is verified.

body · string

Printed in the footer of every email. Without one, sending waits for it.

body · boolean

A public page for each sent issue, with a signup form. On for new newsletters: the website goes live after the first issue.

body · string

One sentence under the name on the archive, 200 characters at most

body · object

The archive's author page; the author's name is fromName

body · string

Under the author's name on the archive, 160 characters at most

body · string

Author photo: an https:// link. The newsletter image otherwise.

body · string[]

https:// links shown on the archive, 8 at most

body · object

Analytics tools on the newsletter's website: each loads on every page of it, never in emails, and hears of each signup there (sign_up for Google Analytics and in Tag Manager's data layer, CompleteRegistration for the Meta pixel). Pasted code keeps only its ID.

body · string

Google Analytics 4's measurement ID, like G-XXXXXXXXXX, or the code Google gives to paste. Empty removes it.

body · string

Google Tag Manager's container ID, like GTM-XXXXXXX, or its code. On the archive domain, only Google's own tags in the container run; on the newsletter's own domain (set_website_domain), all of them.

body · string

The Meta pixel's ID, the digits under its name in Meta Events Manager, or its code.

body · string

HTML for the head of every page of the newsletter's website, like another tool's code: <script>, <style>, <link> and <noscript> tags, with https:// addresses. It runs on the newsletter's own domain only (set_website_domain), never on its address on the archive domain, which other newsletters share. Code that wouldn't work is refused with the line to fix: a tag that isn't closed, text outside a tag, a JavaScript error, a meta tag, an event handler attribute, or Google Analytics, Tag Manager or Meta pixel code, which goes in analytics. Empty removes it.

body · boolean

Confirmed opt-in: new signups get an email with a button and only join once they click it. On for new newsletters. New subscribers get the confirmation email or the welcome email: turning it on while the welcome email is on needs welcome.enabled false in the same request.

body · object

List cleanup at each send: contacts who ignored several issues get a last-chance email instead (lastChance), and become dormant if they don't answer

body · boolean

On for new newsletters

body · number | null

Ignored issues in a row before the last-chance email, 2 to 100. Default 6.

body · number | null

Days without an open, click or signup, 30 to 3650. Default 180.

body · object

Email sent to each new subscriber, while signups don't need confirming: turning it on while requireConfirmation is on needs requireConfirmation false in the same request.

body · boolean

body · string

body · string

body · "rich" | "markdown"

With content: rich or markdown, the default

body · string

The email's body. Merge tags work as in campaigns. rich is an HTML fragment as the dashboard's editor writes it, as update_campaign's format describes, sections aside; markdown is Markdown.

body · string

Markdown: the same as content with format markdown

body · object

The confirmation email for confirmed opt-in. Sent back unchanged, the built-in one stays built-in and follows the name and description.

body · string

body · string

body · "rich" | "markdown"

With content: rich or markdown, the default

body · string

The email's body. It keeps its button, a link to {{confirm_url}}: <div data-button=""><a href="{{confirm_url}}">Its text</a></div>, or the same <a> in Markdown. Merge tags work as in campaigns. rich is an HTML fragment as the dashboard's editor writes it, as update_campaign's format describes, sections aside; markdown is Markdown.

body · string

Markdown: the same as content with format markdown

body · object

The list cleanup's last-chance email, which contacts who stopped opening get instead of an issue: a click on its button keeps them. Write your own to say it in your words or your readers' language. Sent back unchanged, the built-in one stays built-in and follows the name.

body · string

body · string

body · "rich" | "markdown"

With content: rich or markdown, the default

body · string

The email's body. It keeps its button, a link to {{keep_url}}: <div data-button=""><a href="{{keep_url}}">Its text</a></div>, or the same <a> in Markdown. Merge tags work as in campaigns. rich is an HTML fragment as the dashboard's editor writes it, as update_campaign's format describes, sections aside; markdown is Markdown.

body · string

Markdown: the same as content with format markdown

body · object

The signup form for the newsletter's own site. get_signup_form gives the code to paste.

body · boolean

Off for new newsletters

body · "inline" | "card"

inline, the fields and button alone; card, in a box under a headline and a line of text

body · string | null

The card's headline. null: the newsletter's name, as it changes. Empty: no headline.

body · string | null

The line under the card's headline. null: the newsletter's description, as it changes. Empty: no line.

body · boolean

Asks for a first name above the email, optional for readers. Off by default.

body · string

Default: Subscribe

body · string

Default: you@example.com

body · string[]

Sites where browsers show the form, like example.com, which covers its subdomains. Empty: any site. With sites listed, only the script form takes signups: the plain HTML form can't prove which site it's on.

body · object

Its look on its website and in its emails: a preset from list_themes and what's changed on top of it. Send only what changes; null takes a choice back to the preset's.

body · "postroom" | "broadsheet" | "garden" | "midnight" | "poster" | "swiss" | "typewriter" | "sunset"

A preset from list_themes. Another preset starts over from it: the changes made to the one before go, unless this call sends new ones.

body · object | null

Its colors in light mode, which its website shows readers whose device is in light mode or who picked Light, and its emails are written in. Hex colors. null takes one back to the preset's; the other shades derive from these three.

body · object | null

Its colors in dark mode, for readers in dark mode: on its website, and in its emails in mail apps that follow it, like Apple Mail and Outlook. An accent changed in one mode only follows into the other, lighter or darker where its page needs it. Hex colors. null takes one back to the preset's; the other shades derive from these three.

body · object | null

Fonts from list_themes. Mail clients without web fonts, like Gmail, show a close system font.

body · integer | null

Fonts with fewer weights use their closest

body · string | null

Corners of buttons, cards and pictures

body · string | null

Cards and forms on the website. Emails have none.

body · string | null

Line height and space between paragraphs

body · string | null

Emails only: where they sit on a screen wider than them, like a computer's. center, or left like a personal email. Phones show them full width either way.

path · string

The newsletter's ID or slug

path · string

The slug to check

query · string

The newsletter that would take it, by ID or slug: its own slug, and those it had, are available to it

path · string

The newsletter's ID or slug

body · string[]

The addresses it goes to, 5 at most, each its own email. Default: the ones saved with saveAsDefault, else the account owner's.

body · boolean

True: once it's sent, these addresses are where the next tests go without to, the dashboard's included

body · string

A contact of the newsletter, by ID or email address, the test reads as. It doesn't get the test. Default: each address as the newsletter's contact it is, or as a sample reader called Jane.

path · string

The newsletter's ID or slug

body · string

A subdomain of a domain you manage, like news.example.com. A link works too.

path · string

The newsletter's ID or slug

path · string

The newsletter's ID or slug

path · string

The newsletter's ID or slug

path · string

The newsletter's ID or slug

body · string

Their name, as the team shows it, 60 characters at most

body · string

The address the invitation goes to, which they sign in with

body · "admin" | "member"

admin: Everything on this newsletter: writing, sending, contacts and settings. Not domains or API keys. member: Writes and edits drafts, sends tests to the team, and adds, imports and edits contacts. Doesn't send, change settings, export or delete.

path · string

The newsletter's ID or slug

path · string

The team member's ID, from list_team_members

body · "admin" | "member"

admin: Everything on this newsletter: writing, sending, contacts and settings. Not domains or API keys. member: Writes and edits drafts, sends tests to the team, and adds, imports and edits contacts. Doesn't send, change settings, export or delete.

body · string

Their name, as the team shows it, 60 characters at most

path · string

The newsletter's ID or slug

path · string

The team member's ID, from list_team_members

query · integer

Notifications per page, 20 by default, 50 at most

query · string

nextCursor from the previous page

body · string[]

Their IDs, from list_notifications. Default: every unread one

body · string[]

Their IDs, from list_notifications. Default: every one

body · string

ISO 8601 date and time: the newest at you listed clears those and older, and keeps what came in since

query · string

Only this newsletter's: its ID or slug. Default: every newsletter.

query · "draft" | "scheduled" | "sending" | "paused" | "sent"

Only campaigns with this status

query · integer

How many, 50 by default, 200 at most

path · string

The campaign's ID

path · string

The campaign's ID

path · string

The campaign's ID

query · "all" | "opened" | "clicked" | "unopened" | "undelivered" | "bounced" | "unsubscribed"

all: everyone it went to, the default. opened, clicked: who opened or clicked it. unopened: delivered, and not opened, bounced or marked as spam. undelivered: not delivered and no hard bounce, so on its way or turned away by their inbox, like a full mailbox. bounced: hard bounces. unsubscribed: who unsubscribed through it.

query · integer

Recipients per page, 50 by default, 100 at most

query · string

nextCursor from the previous page

body · string

The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.

body · string

Subject line, 200 characters at most. {{first_name}} prints each reader's first name, and {{key}} their value for one of the account's fields (list_contact_fields): a number as 1,250, a date as April 12, 1991. {{first_name|friend}} prints "friend" for a reader without one. The website always prints the fallback, and any other {{...}} goes out as written.

body · string

Text inbox apps show after the subject, 300 characters at most. Merge tags work as in the subject.

body · "markdown" | "rich" | "html"

markdown (the default when content is given), rich or html, as in update_campaign

body · string

The body in that format, 500 KB at most. Merge tags work as in the subject.

body · string

The issue's page path once sent. Default: made from the subject; a taken slug gets a number.

body · string | null

A segment's ID (list_segments): only the active contacts it picks when the campaign goes out get it. null: every active contact.

body · "both" | "email" | "web"

Where it goes, both by default. both: sent to the contacts and on the newsletter's website (the default). email: sent, but never on the website, and its emails have no Read online link. web: on the website only, no email goes out, so no recipients, audience limit or segment; send_campaign and schedule_campaign publish it.

body · string

Who wrote it: an author's ID (list_authors, create_author) of the campaign's newsletter. Their name, and their picture if any, show as "By <name>" in its emails and on its page, where the author says they show, and replies to it go to their email. It can't be sent or scheduled without one. Default: the newsletter's default author (isDefault on list_authors).

path · string

The campaign's ID

body · string

Subject line, 200 characters at most. {{first_name}} prints each reader's first name, and {{key}} their value for one of the account's fields (list_contact_fields): a number as 1,250, a date as April 12, 1991. {{first_name|friend}} prints "friend" for a reader without one. The website always prints the fallback, and any other {{...}} goes out as written.

body · string

Text inbox apps show after the subject, 300 characters at most. Merge tags work as in the subject.

body · "markdown" | "rich" | "html"

With content: the format it's in. Default: the campaign's current format. markdown: Markdown laid out in the newsletter's design. rich: an HTML fragment (paragraphs, headings, links, images) in the same design, what the dashboard editor writes; its styles and classes are dropped, except in an HTML block, <div data-html-block="">, which holds HTML escaped as text (&lt;table style="…"&gt;) and keeps its inline styles, tables and layout attributes, without scripts, forms, frames or style tags. In both, a button is <div data-button=""><a href="https://…">Its text</a></div>, drawn in the newsletter's button colors and corners, centered unless the <div> has data-align="left" or "right"; it can't be sent without text and an https://, http:// or mailto: link. In rich content, a section shows what's in it to some readers only, or only in emails or on the website: <section data-section="" data-show="tag:vip" data-where="email">…</section>. data-show (only those readers) or data-hide (everyone except them), not both, is tag:<tag>, percent-encoded like a link (tag:early%20bird), or segment:<id> (list_segments); data-where is "email" or "web", and without them everyone sees it, in emails and on the website. Who sees it only counts in emails: the website shows its sections to every visitor, so one for some readers usually has data-where="email". Readers who don't match get the rest of the issue without it. 20 sections and 10 different tags or segments at most, none inside another or in an HTML block's HTML (around a block is fine); markdown and html can't hold them. html: a complete HTML email sent as is, with the footer added unless it contains {{unsubscribe_url}}.

body · string

The body in that format, 500 KB at most. Merge tags work as in the subject.

body · string | null

A segment's ID (list_segments): only the active contacts it picks when the campaign goes out get it. null: every active contact.

body · "both" | "email" | "web"

both: sent to the contacts and on the newsletter's website (the default). email: sent, but never on the website, and its emails have no Read online link. web: on the website only, no email goes out, so no recipients, audience limit or segment; send_campaign and schedule_campaign publish it.

body · string

Who wrote it: an author's ID (list_authors, create_author) of the campaign's newsletter. Their name, and their picture if any, show as "By <name>" in its emails and on its page, where the author says they show, and replies to it go to their email. It can't be sent or scheduled without one.

body · integer

The campaign's revision the change starts from (get_campaign's): if its subject, preview text or content changed since, nothing changes and it answers revision_conflict, so a change never writes over someone else's. Without it, the change lands whatever happened since.

path · string

The campaign's ID

path · string

The campaign's ID

path · string

The campaign's ID

query · string

A contact of the campaign's newsletter, by ID or email address. Default: a sample reader called Jane.

path · string

The campaign's ID

body · string[]

tag:<tag> or segment:<id>, as in a section's data-show or data-hide, 10 at most. Default: those its sections name.

body · boolean

True: every tag the newsletter's contacts have, the 200 most used, those most of its readers have first, then every segment, in place of groups

path · string

The campaign's ID

body · string[]

The addresses it goes to, 5 at most, each its own email. Default: the ones saved with saveAsDefault, else the account owner's.

body · boolean

True: once it's sent, these addresses are where the next tests go without to, the dashboard's included

body · string

A contact of the campaign's newsletter, by ID or email address, the test reads as. It doesn't get the test. Default: each address as the newsletter's contact it is, or as a sample reader called Jane.

path · string

The campaign's ID

body · string

ISO 8601 date and time, e.g. 2026-10-20T09:00:00Z, at least a minute ahead

body · integer

Send to this many contacts at most, the most engaged first. The rest can follow with send_campaign_to_more.

body · string | null

A segment's ID (list_segments): only the active contacts it picks when the campaign goes out get it. null: every active contact. Default: the campaign's segment.

path · string

The campaign's ID

path · string

The campaign's ID

body · integer

Send to this many contacts at most, the most engaged first. The rest can follow with send_campaign_to_more.

body · string | null

A segment's ID (list_segments): only the active contacts it picks get it. null: every active contact. Default: the campaign's segment.

path · string

The campaign's ID

body · integer

How many more contacts. Default: everyone who hasn't received it.

path · string

The campaign's ID

path · string

The campaign's ID

path · string

The campaign's ID

body · string

Lowercase letters, digits and dashes. Empty removes it from a draft.

body · boolean

Pinned issues lead the archive

body · string

The page's title, on the website's cards and in link previews too, instead of the subject. Empty: the subject again. 200 characters at most; merge tags print their fallback, as on the website.

body · string

The line under the title, on the page and its cards and in link previews, instead of the preview text. Empty: the preview text again. 300 characters at most.

body · string

The picture of the page's cards on the website and of its link previews: the https:// URL of one of the page's own pictures or of an image upload_image stored, card for the card Postroom draws with the title, or empty for the content's first picture, the default.

body · string | null

Once the campaign is on the website: the page's own content in format, 500 KB at most, which leaves its emails as they were sent. null: the email's content again. Sections show as on the website, so those for emails only go.

body · "markdown" | "rich" | "html"

With content: the format it's in, as in update_campaign. Default: the page's current format.

path · string

The campaign's ID

path · string

The campaign's ID

query · integer

Count for a send capped at this many contacts

query · boolean

Also return, for each cold contact, how many issue recipients come before it, to recount any limit without asking again

query · string

The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.

body · string

The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.

body · string

The name readers see, 60 characters at most, on one line, without braces or angle brackets

body · string

Where replies to their issues go (their Reply-To). It never shows on an issue or its page.

body · string

Their picture, next to their name: an https:// image URL, like one upload_image returns. Empty for none.

body · boolean

Their name under the title of their issues' pages on the website. Default: true.

body · boolean

Their name at the top of their issues' emails. Default: true.

path · string

The author's ID

body · string

The name readers see, 60 characters at most, on one line, without braces or angle brackets

body · string

Where replies to their issues go (their Reply-To). It never shows on an issue or its page.

body · string

Their picture, next to their name: an https:// image URL, like one upload_image returns. Empty for none.

body · boolean

Their name under the title of their issues' pages on the website. Default: true.

body · boolean

Their name at the top of their issues' emails. Default: true.

body · boolean

true makes them the default author, in the place of the one before: new campaigns start with them. Campaigns that have an author keep theirs.

path · string

The author's ID

query · string

Only this newsletter's: its ID or slug. Default: every newsletter.

query · "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant"

Only contacts with this status

query · string

Only the contacts a segment picks (its ID, from list_segments), whatever their status unless status is given. With newsletter, one of that newsletter's segments.

query · string

Only contacts with this tag

query · string

Only contacts from this source: website, embed, import, dashboard, api, or a source an API caller gave (list_contact_sources)

query · string

Only contacts who signed up on this day or after it, YYYY-MM-DD (UTC)

query · string

Only contacts who signed up before this day, YYYY-MM-DD (UTC)

query · string

Contacts whose email contains this, like @example.com for everyone at a domain. * stands for any characters: jane*@example.com.

query · integer

Contacts per page, 50 by default, 100 at most

query · string

nextCursor from the previous page

query · string

Only this newsletter's: its ID or slug. Default: every newsletter.

query · string

Part of the email address or of the first name, like @example.com for everyone at a domain

query · "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant"

Only contacts with this status

query · integer

How many, 10 by default, 20 at most

query · string[]

Segment IDs (list_segments), 10 at most: each contact's inSegments says which of them it's in now

path · string

The contact's ID or email address

query · string

The newsletter's ID or slug, needed for an email address that is a contact of several newsletters

path · string

The contact's ID or email address

query · string

The newsletter's ID or slug, needed for an email address that is a contact of several newsletters

query · integer

Emails per page, 50 by default, 100 at most

query · string

nextCursor from the previous page

body · string

The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.

body · string

The subscriber's email address

body · string | null

Their first name, which {{first_name}} prints in emails. For a contact who signs up again, only saved if they had none.

body · string[]

Tags to add, lowercase, no commas. A contact who signs up again keeps theirs and gets these too.

body · object

Values for the account's own fields, by key (list_contact_fields). For a contact who signs up again, only the ones they had no value for.

body · string

Where they signed up, e.g. website. Default: api.

body · boolean

Bring back a contact who unsubscribed or went dormant. Someone who unsubscribed gets the confirmation email and stays pending until they click it. Bounced and complained addresses never come back, nor does a contact deleted after it unsubscribed.

body · string

The visitor's IP address: one visitor gets 5 signups in 10 minutes

path · string

The contact's ID or email address

body · string

The newsletter's ID or slug, needed for an email address that is a contact of several newsletters

body · string | null

The first name {{first_name}} prints in emails. null or "" removes it.

body · string[]

The contact's tags, replacing the ones it has. [] removes them all.

body · object

Values for the account's own fields, by key (list_contact_fields): text, a number, or YYYY-MM-DD for a date. null removes one.

path · string

The contact's ID or email address

body · string

The newsletter's ID or slug, needed for an email address that is a contact of several newsletters

body · "active" | "dormant" | "unsubscribed"

active, dormant or unsubscribed

body · boolean

true when the person asked for it: needed to resubscribe someone who unsubscribed, or to make a pending contact active

body · string

The newsletter's ID or slug, needed for an email address that is a contact of several newsletters

body · string[]

Contact IDs or email addresses, 1,000 at most. An address matches its contact in every newsletter unless newsletter is given.

body · object

Instead of contacts: every contact of the newsletter these pick, like list_contacts' filters. Needs newsletter.

body · string

Only the contacts a segment picks (its ID, from list_segments), whatever their status unless status is given. With newsletter, one of that newsletter's segments.

body · "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant"

Only contacts with this status

body · string

Only contacts with this tag

body · string

Only contacts from this source: website, embed, import, dashboard, api, or a source an API caller gave (list_contact_sources)

body · string

Only contacts who signed up on this day or after it, YYYY-MM-DD (UTC)

body · string

Only contacts who signed up before this day, YYYY-MM-DD (UTC)

body · string

Contacts whose email contains this, like @example.com for everyone at a domain. * stands for any characters: jane*@example.com.

body · boolean

true instead of contacts or filter: every contact of the newsletter. Needs newsletter.

body · "active" | "dormant" | "unsubscribed"

active, dormant or unsubscribed

body · string

The newsletter's ID or slug, needed for an email address that is a contact of several newsletters

body · string[]

Contact IDs or email addresses, 1,000 at most. An address matches its contact in every newsletter unless newsletter is given.

body · object

Instead of contacts: every contact of the newsletter these pick, like list_contacts' filters. Needs newsletter.

body · string

Only the contacts a segment picks (its ID, from list_segments), whatever their status unless status is given. With newsletter, one of that newsletter's segments.

body · "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant"

Only contacts with this status

body · string

Only contacts with this tag

body · string

Only contacts from this source: website, embed, import, dashboard, api, or a source an API caller gave (list_contact_sources)

body · string

Only contacts who signed up on this day or after it, YYYY-MM-DD (UTC)

body · string

Only contacts who signed up before this day, YYYY-MM-DD (UTC)

body · string

Contacts whose email contains this, like @example.com for everyone at a domain. * stands for any characters: jane*@example.com.

body · boolean

true instead of contacts or filter: every contact of the newsletter. Needs newsletter.

body · string[]

Tags, 10 at most. Tags are lowercase.

body · string

The newsletter's ID or slug, needed for an email address that is a contact of several newsletters

body · string[]

Contact IDs or email addresses, 1,000 at most. An address matches its contact in every newsletter unless newsletter is given.

body · object

Instead of contacts: every contact of the newsletter these pick, like list_contacts' filters. Needs newsletter.

body · string

Only the contacts a segment picks (its ID, from list_segments), whatever their status unless status is given. With newsletter, one of that newsletter's segments.

body · "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant"

Only contacts with this status

body · string

Only contacts with this tag

body · string

Only contacts from this source: website, embed, import, dashboard, api, or a source an API caller gave (list_contact_sources)

body · string

Only contacts who signed up on this day or after it, YYYY-MM-DD (UTC)

body · string

Only contacts who signed up before this day, YYYY-MM-DD (UTC)

body · string

Contacts whose email contains this, like @example.com for everyone at a domain. * stands for any characters: jane*@example.com.

body · boolean

true instead of contacts or filter: every contact of the newsletter. Needs newsletter.

body · string[]

Tags, 10 at most. Tags are lowercase.

path · string

The contact's ID or email address

query · string

The newsletter's ID or slug, needed for an email address that is a contact of several newsletters

body · string

The newsletter's ID or slug, needed for an email address that is a contact of several newsletters

body · string[]

Contact IDs or email addresses, 1,000 at most. An address matches its contact in every newsletter unless newsletter is given.

body · object

Instead of contacts: every contact of the newsletter these pick, like list_contacts' filters. Needs newsletter.

body · string

Only the contacts a segment picks (its ID, from list_segments), whatever their status unless status is given. With newsletter, one of that newsletter's segments.

body · "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant"

Only contacts with this status

body · string

Only contacts with this tag

body · string

Only contacts from this source: website, embed, import, dashboard, api, or a source an API caller gave (list_contact_sources)

body · string

Only contacts who signed up on this day or after it, YYYY-MM-DD (UTC)

body · string

Only contacts who signed up before this day, YYYY-MM-DD (UTC)

body · string

Contacts whose email contains this, like @example.com for everyone at a domain. * stands for any characters: jane*@example.com.

body · boolean

true instead of contacts or filter: every contact of the newsletter. Needs newsletter.

body · string

The newsletter's ID or slug, needed for an email address that is a contact of several newsletters

body · string[]

Contact IDs or email addresses, 1,000 at most. An address matches its contact in every newsletter unless newsletter is given.

body · object

Instead of contacts: every contact of the newsletter these pick, like list_contacts' filters. Needs newsletter.

body · string

Only the contacts a segment picks (its ID, from list_segments), whatever their status unless status is given. With newsletter, one of that newsletter's segments.

body · "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant"

Only contacts with this status

body · string

Only contacts with this tag

body · string

Only contacts from this source: website, embed, import, dashboard, api, or a source an API caller gave (list_contact_sources)

body · string

Only contacts who signed up on this day or after it, YYYY-MM-DD (UTC)

body · string

Only contacts who signed up before this day, YYYY-MM-DD (UTC)

body · string

Contacts whose email contains this, like @example.com for everyone at a domain. * stands for any characters: jane*@example.com.

body · boolean

true instead of contacts or filter: every contact of the newsletter. Needs newsletter.

body · string

The segment's name, 60 characters at most

body · string

The tag they get, which the segment picks. Default: the name, lowercase.

path · string

The id the change answered with

body · string

The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.

body · boolean

Must be true: These people agreed to receive my emails. Bought or scraped lists aren't allowed.

body · object[]

The rows, 1000 at most

body · string

Invalid addresses are left out and counted

body · "active" | "dormant" | "unsubscribed" | "bounced" | "complained"

active (default), dormant, unsubscribed, bounced or complained

body · string

When they signed up, ISO 8601

body · number

Emails they got on the previous platform

body · number

0 to 1, from the previous platform: sends reach the most engaged first

body · number

0 to 1, from the previous platform

body · string

Their last open on the previous platform, ISO 8601: segments on opens use it

body · string

Their last click on the previous platform, ISO 8601

body · integer

How many emails they opened on the previous platform

body · integer

How many emails they clicked on the previous platform

body · string

Their first name, replacing the contact's

body · string[]

Tags added to the contact's own

body · object

Values for the account's own fields, by key: values that don't fit the field's type are left out

body · string

The importId of the first chunk, to add rows to the same import

body · integer

With the first chunk: the rows the whole import sends, so its status turns done once they're all processed

body · integer

Duplicates you removed before sending, counted in the import's report

path · string

The importId import_contacts answered with

query · string

Only this newsletter's: its ID or slug. Default: every newsletter.

query · integer

How many, 5 by default

path · string

The importId import_contacts answered with

query · string

Only addresses containing this. * stands for any characters: info@*.co.za.

query · string

The nextCursor of the previous page

query · integer

How many, 50 by default

path · string

The importId import_contacts answered with

body · string[]

The addresses, as list_left_out gives them, 100 at most

query · string

Only this newsletter's: its ID or slug. Default: every newsletter.

query · "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant"

Only contacts with this status

query · string

Only the contacts a segment picks (its ID, from list_segments), whatever their status unless status is given. With newsletter, one of that newsletter's segments.

query · string

Only contacts with this tag

query · string

Only contacts from this source: website, embed, import, dashboard, api, or a source an API caller gave (list_contact_sources)

query · string

Only contacts who signed up on this day or after it, YYYY-MM-DD (UTC)

query · string

Only contacts who signed up before this day, YYYY-MM-DD (UTC)

query · string

Contacts whose email contains this, like @example.com for everyone at a domain. * stands for any characters: jane*@example.com.

query · string

Only this newsletter's: its ID or slug. Default: every newsletter.

query · string

Only this newsletter's: its ID or slug. Default: every newsletter.

body · string

The field's name, 40 characters at most

body · "text" | "number" | "date"

text, number or date

path · string

The field's key, from list_contact_fields

query · string

Only this newsletter's: its ID or slug. Default: every newsletter.

path · string

The segment's ID

body · string

The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.

body · "all" | "any"

all: contacts meeting every condition (the default). any: contacts meeting at least one.

body · object[]

The conditions, 10 at most. Dates count back from each send, so "within 30 days" moves with time.

body · string

opened, clicked: the last open or click (a click counts as an open). missed_issues: issues received in a row without opening or clicking any. emails_opened: emails opened in all. signed_up: the signup date. source: where the contact came from (website, import, dashboard, api, or a source an API caller gave). email: the address. tag: one of the contact's tags. first_name: whether the contact has a first name. fields.<key>: one of the account's own fields (list_contact_fields).

body · "within" | "not_within" | "never" | "at_least" | "less_than" | "before" | "since" | "is" | "is_not" | "contains" | "ends_with" | "has" | "has_not" | "is_set" | "not_set"

opened, clicked: within, not_within (days) or never. missed_issues, emails_opened: at_least or less_than (a number). signed_up: within, not_within (days), before or since (a date). source: is or is_not. email: contains or ends_with. tag: has or has_not. first_name: is_set or not_set. fields.<key>: is, contains, is_set or not_set for text; at_least, less_than, is_set or not_set for numbers; before, since, is_set or not_set for dates.

body · number | string

Days (1 to 3650) for within and not_within, a number for at_least and less_than, YYYY-MM-DD (UTC) for before and since, a tag for has and has_not, text for the rest. None for never, is_set and not_set.

body · string

The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.

body · string

The segment's name, 60 characters at most

body · "all" | "any"

all: contacts meeting every condition (the default). any: contacts meeting at least one.

body · object[]

The conditions, 10 at most. Dates count back from each send, so "within 30 days" moves with time.

body · string

opened, clicked: the last open or click (a click counts as an open). missed_issues: issues received in a row without opening or clicking any. emails_opened: emails opened in all. signed_up: the signup date. source: where the contact came from (website, import, dashboard, api, or a source an API caller gave). email: the address. tag: one of the contact's tags. first_name: whether the contact has a first name. fields.<key>: one of the account's own fields (list_contact_fields).

body · "within" | "not_within" | "never" | "at_least" | "less_than" | "before" | "since" | "is" | "is_not" | "contains" | "ends_with" | "has" | "has_not" | "is_set" | "not_set"

opened, clicked: within, not_within (days) or never. missed_issues, emails_opened: at_least or less_than (a number). signed_up: within, not_within (days), before or since (a date). source: is or is_not. email: contains or ends_with. tag: has or has_not. first_name: is_set or not_set. fields.<key>: is, contains, is_set or not_set for text; at_least, less_than, is_set or not_set for numbers; before, since, is_set or not_set for dates.

body · number | string

Days (1 to 3650) for within and not_within, a number for at_least and less_than, YYYY-MM-DD (UTC) for before and since, a tag for has and has_not, text for the rest. None for never, is_set and not_set.

path · string

The segment's ID

body · string

The segment's name, 60 characters at most

body · "all" | "any"

all: contacts meeting every condition (the default). any: contacts meeting at least one.

body · object[]

The conditions, 10 at most. Dates count back from each send, so "within 30 days" moves with time.

body · string

opened, clicked: the last open or click (a click counts as an open). missed_issues: issues received in a row without opening or clicking any. emails_opened: emails opened in all. signed_up: the signup date. source: where the contact came from (website, import, dashboard, api, or a source an API caller gave). email: the address. tag: one of the contact's tags. first_name: whether the contact has a first name. fields.<key>: one of the account's own fields (list_contact_fields).

body · "within" | "not_within" | "never" | "at_least" | "less_than" | "before" | "since" | "is" | "is_not" | "contains" | "ends_with" | "has" | "has_not" | "is_set" | "not_set"

opened, clicked: within, not_within (days) or never. missed_issues, emails_opened: at_least or less_than (a number). signed_up: within, not_within (days), before or since (a date). source: is or is_not. email: contains or ends_with. tag: has or has_not. first_name: is_set or not_set. fields.<key>: is, contains, is_set or not_set for text; at_least, less_than, is_set or not_set for numbers; before, since, is_set or not_set for dates.

body · number | string

Days (1 to 3650) for within and not_within, a number for at_least and less_than, YYYY-MM-DD (UTC) for before and since, a tag for has and has_not, text for the rest. None for never, is_set and not_set.

path · string

The segment's ID

body · string

e.g. example.com. An address or a link works too: jane@example.com and https://www.example.com/about both add example.com.

path · string

The domain's ID

path · string

The domain's ID

query · integer

Images per page, 50 by default, 100 at most

query · string

nextCursor from the previous page

body · string

The image file, base64 encoded; a data: URL works too

body · string

An https:// link to the image

body · string

Used in the stored file's name

body · string

The file's type, checked against its first bytes

body · string

What the key is for, e.g. Website signups

body · "full" | "signups"

full or signups

path · string

The API key's ID

path · string

The connected app's ID