API reference

query · string

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

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

The shared address (hello@<slug>.<shared domain>, set automatically) or an address on a domain added to this account

body · string

Where replies go. Empty: replies to the shared address go to the account owner.

body · string

Printed in the footer of every email. Never set, it's the server's default (MailCheap's address on MailCheap Cloud, none on a self-hosted server); saved empty, there's none and sending waits for one.

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 · 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, 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 · string

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 · string

Markdown that keeps the button: an HTML link like <a href="{{confirm_url}}">Confirm</a>

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: Iscriviti

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 · "mailcheap" | "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

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

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 MailCheap keeps like www, api or mail. The shared from address (hello@<slug>.<shared domain>) and the archive subdomain follow it.

body · string

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

body · string

Name in the From field

body · string

The shared address (hello@<slug>.<shared domain>, set automatically) or an address on a domain added to this account

body · string

Where replies go. Empty: replies to the shared address go to the account owner.

body · string

Printed in the footer of every email. Never set, it's the server's default (MailCheap's address on MailCheap Cloud, none on a self-hosted server); saved empty, there's none and sending waits for one.

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 · 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, 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 · string

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 · string

Markdown that keeps the button: an HTML link like <a href="{{confirm_url}}">Confirm</a>

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: Iscriviti

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 · "mailcheap" | "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

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

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 is available to it

path · string

The newsletter's ID or slug

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

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

body · string

Text inbox apps show after the subject, 300 characters at most

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

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.

path · string

The campaign's ID

body · string

Subject line, 200 characters at most

body · string

Text inbox apps show after the subject, 300 characters at most

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

With content: the format it's in. Default: the campaign's current format.

body · string

The body in that format, 500 KB at most

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.

path · string

The campaign's ID

path · string

The campaign's ID

path · string

The campaign's ID

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

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

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

Contacts whose email starts with this

query · integer

Contacts per page, 50 by default, 100 at most

query · string

nextCursor from the previous page

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. 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. 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

Contacts whose email starts with this

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

Contacts whose email starts with this

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. Default: the account's first newsletter, the one it has had longest.

body · boolean

Must be true: Queste persone hanno accettato di ricevere le mie mail. 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

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

Contacts whose email starts with this

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.

body · string

Used when the domain's setup lists an archive step: the subdomain for the archive, tracked links and unsubscribe links. Default: news.<domain>.

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

body · "starter" | "growth" | "pro" | "scale" | "max"

starter, growth, pro, scale or max

body · "month" | "year"

month (default) or year, which costs 10 months