Reference

API reference

Base URL https://newsletter.adityakhare.com/api/v1. Bodies are JSON; GET and DELETE take their parameters in the query string. Each endpoint is also the MCP tool named under it. The same reference as OpenAPI 3.1.

Overview

Subscribers, email results and sends per hour, as on the dashboard's first page.

Get the overview

GET/api/v1/overview

The dashboard's overview for one newsletter: subscribers each day of the last 30 days, email results of the last 30 days against the 30 before, emails sent per hour today and yesterday, and the plan's usage this month, which the account's newsletters share.

MCP toolget_overviewKeyFull accessRead-onlySafe to repeat

Parameter Description

Parameter	Description
`newsletter` query · string The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.	The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.
`timeZone` query · string IANA time zone for days and hours, e.g. Europe/Paris. Default: UTC.	IANA time zone for days and hours, e.g. Europe/Paris. Default: UTC.

newsletter

query · string

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

timeZone

query · string

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

Request

curl "https://newsletter.adityakhare.com/api/v1/overview?timeZone=Europe%2FParis" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Get a summary

GET/api/v1/summary

What MailCheap's summary email says about one newsletter, for its last whole day or week: who joined and who unsubscribed against the period before, the total, new subscribers per day for the last 14 days or per week for the last 8 weeks, the latest issue's open and click rates against the newsletter's average with its most clicked link, and the summary's opening line.

MCP toolget_summaryKeyFull accessRead-onlySafe to repeat

Parameter Description

Parameter	Description
`newsletter` query · string The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.	The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.
`period` query · "day" \| "week" day: yesterday. week: the 7 days before the latest Monday. Default: week.	day: yesterday. week: the 7 days before the latest Monday. Default: week.
`timeZone` query · string IANA time zone the days start in, e.g. Europe/Paris. Default: UTC.	IANA time zone the days start in, e.g. Europe/Paris. Default: UTC.

newsletter

query · string

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

period

query · "day" | "week"

day: yesterday. week: the 7 days before the latest Monday. Default: week.

timeZone

query · string

IANA time zone the days start in, e.g. Europe/Paris. Default: UTC.

Request

curl "https://newsletter.adityakhare.com/api/v1/summary?period=week&timeZone=Europe%2FParis" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Newsletters

Sender, postal address, welcome and confirmation emails, list cleanup, archive and theme.

List newsletters

GET/api/v1/newsletters

Lists the account's newsletters, 3 at most, first created first, with their settings and active contacts. Actions that take a newsletter use the first one when it's left out.

MCP toollist_newslettersKeyFull accessRead-onlySafe to repeat

Request

curl "https://newsletter.adityakhare.com/api/v1/newsletters" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Get a newsletter

GET/api/v1/newsletters/{id}

Gets a newsletter's settings: sender, postal address, welcome and confirmation emails, list cleanup, archive and theme.

MCP toolget_newsletterKeyFull accessRead-onlySafe to repeat

Parameter Description

idrequired

path · string

The newsletter's ID or slug

Request

curl "https://newsletter.adityakhare.com/api/v1/newsletters/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Create a newsletter

POST/api/v1/newsletters

Creates a newsletter. An account has up to 3, sharing its plan's emails and subscribers; one more answers conflict. Without a fromEmail it sends from the shared address hello@<slug>.<shared domain>, which MailCheap sets up in a few minutes. List cleanup is on unless cleanup.enabled is false. Without a postalAddress, its emails print the server's default if it has one: MailCheap's address on MailCheap Cloud.

MCP toolcreate_newsletterKeyFull access

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/newsletters" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Field notes","postalAddress":"Field Notes Ltd, 1 Main St, Paris, France"}'

Update a newsletter

PATCH/api/v1/newsletters/{id}

Changes a newsletter's settings. Send only the fields to change; nested groups (welcome, confirmation, cleanup, author) keep the fields you leave out. An account changes slugs 3 times a day at most: one more answers rate_limited.

MCP toolupdate_newsletterKeyFull accessSafe to repeat

Request

curl -X PATCH "https://newsletter.adityakhare.com/api/v1/newsletters/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"replyTo":"jane@example.com","requireConfirmation":true}'

List themes

GET/api/v1/themes

Lists the theme presets a newsletter can take, with their colors, fonts and choices, and the options to change them with: fonts, heading weights, radius, shadow and spacing. update_newsletter's theme sets them.

MCP toollist_themesKeyFull accessRead-onlySafe to repeat

Request

curl "https://newsletter.adityakhare.com/api/v1/themes" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Get the signup form

GET/api/v1/newsletters/{id}/signup-form

Gets the signup form for a newsletter's own site: its settings and the code to paste there. script adds it in the newsletter's theme, in a frame that fits its content; html is a plain form that works without JavaScript and lands on a page that says what happened, null while sites are listed. Both post to endpoint, which takes an email from a browser on any site (CORS, JSON or form fields) while the form is on and follows the newsletter's confirmed opt-in and welcome email; from your own code, use add_contact with a signups-only key instead. update_newsletter's signupForm turns it on and sets its text and sites.

MCP toolget_signup_formKeyFull accessRead-onlySafe to repeat

Parameter Description

idrequired

path · string

The newsletter's ID or slug

Request

curl "https://newsletter.adityakhare.com/api/v1/newsletters/6650f1c2e9b1d4a012345678/signup-form" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Check a slug

GET/api/v1/newsletters/slugs/{slug}

Says whether a newsletter can take a slug: available, or taken by another newsletter, reserved by MailCheap or invalid, with the message saving it would answer. Checking doesn't count toward the 3 slug changes a day.

MCP toolcheck_newsletter_slugKeyFull accessRead-onlySafe to repeat

Parameter Description

Parameter	Description
`slug`required path · string The slug to check	The slug to check
`id` query · string The newsletter that would take it, by ID or slug: its own slug is available to it	The newsletter that would take it, by ID or slug: its own slug is available to it

slugrequired

path · string

The slug to check

id

query · string

The newsletter that would take it, by ID or slug: its own slug is available to it

Request

curl "https://newsletter.adityakhare.com/api/v1/newsletters/slugs/6650f1c2e9b1d4a012345678?slug=field-notes" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Send a test of the welcome email

POST/api/v1/newsletters/{id}/welcome-test

Sends the saved welcome email to the account owner's address, switched on or not. It counts toward the plan's emails.

MCP toolsend_welcome_test_emailKeyFull accessReaches outside MailCheap

Parameter Description

idrequired

path · string

The newsletter's ID or slug

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/newsletters/6650f1c2e9b1d4a012345678/welcome-test" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Campaigns

Drafts, test emails, scheduling, sending, sending in steps and reports.

List campaigns

GET/api/v1/campaigns

Lists campaigns, newest activity first: sent issues by send date, scheduled ones by send time, drafts by last edit. Content is left out; get_campaign has it.

MCP toollist_campaignsKeyFull accessRead-onlySafe to repeat

Parameter Description

newsletter

query · string

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

status

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

Only campaigns with this status

limit

query · integer

How many, 50 by default, 200 at most

Request

curl "https://newsletter.adityakhare.com/api/v1/campaigns?status=sent&limit=10" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Get a campaign

GET/api/v1/campaigns/{id}

Gets a campaign with its content, stats and, for drafts, what would block sending it now.

MCP toolget_campaignKeyFull accessRead-onlySafe to repeat

Parameter Description

idrequired

path · string

The campaign's ID

Request

curl "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Get a campaign's report

GET/api/v1/campaigns/{id}/report

Delivery, open, click, bounce, complaint and unsubscribe rates of a sent campaign, how they compare with the newsletter's earlier issues, its opens and clicks hour by hour after sending, the clicks on each of its links, its list cleanup emails, results by inbox provider, and how many contacts a capped send hasn't reached yet.

MCP toolget_campaign_reportKeyFull accessRead-onlySafe to repeat

Parameter Description

idrequired

path · string

The campaign's ID

Request

curl "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/report" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Create a draft campaign

POST/api/v1/campaigns

Creates a draft. Nothing is sent: review it in the dashboard or with get_campaign, then send_test_email, schedule_campaign or send_campaign.

MCP toolcreate_campaignKeyFull access

Parameter	Description
`newsletter` body · string The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.	The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.
`subject` body · string Subject line, 200 characters at most	Subject line, 200 characters at most
`previewText` body · string Text inbox apps show after the subject, 300 characters at most	Text inbox apps show after the subject, 300 characters at most
`format` body · "markdown" \| "rich" \| "html" markdown (the default when content is given), rich or html, as in update_campaign	markdown (the default when content is given), rich or html, as in update_campaign
`content` body · string The body in that format, 500 KB at most	The body in that format, 500 KB at most
`archiveSlug` body · string The issue's page path once sent. Default: made from the subject; a taken slug gets a number.	The issue's page path once sent. Default: made from the subject; a taken slug gets a number.
`segment` 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.	A segment's ID (list_segments): only the active contacts it picks when the campaign goes out get it. null: every active contact.

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/campaigns" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"This week","previewText":"Three links worth your time","content":"# This week\n\nThree links worth your time."}'

Update a draft campaign

PATCH/api/v1/campaigns/{id}

Changes a draft or scheduled campaign's subject, preview text, content or segment. Send only the fields to change; format goes with content. Sent campaigns can't change.

MCP toolupdate_campaignKeyFull accessSafe to repeat

Parameter	Description
`id`required path · string The campaign's ID	The campaign's ID
`subject` body · string Subject line, 200 characters at most	Subject line, 200 characters at most
`previewText` body · string Text inbox apps show after the subject, 300 characters at most	Text inbox apps show after the subject, 300 characters at most
`format` body · "markdown" \| "rich" \| "html" With content: the format it's in. Default: the campaign's current format.	With content: the format it's in. Default: the campaign's current format.
`content` body · string The body in that format, 500 KB at most	The body in that format, 500 KB at most
`segment` 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.	A segment's ID (list_segments): only the active contacts it picks when the campaign goes out get it. null: every active contact.

Request

curl -X PATCH "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"This week, and one more link"}'

Delete a draft campaign

DELETE/api/v1/campaigns/{id}

Deletes a draft or scheduled campaign: it leaves every list and a scheduled send never goes out. Sent campaigns can't be deleted.

MCP tooldelete_campaignKeyFull accessCan't be undoneSafe to repeat

Parameter Description

idrequired

path · string

The campaign's ID

Request

curl -X DELETE "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Duplicate a campaign

POST/api/v1/campaigns/{id}/duplicate

Copies a campaign's subject, preview text and content into a new draft.

MCP toolduplicate_campaignKeyFull access

Parameter Description

idrequired

path · string

The campaign's ID

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/duplicate" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Send a test email

POST/api/v1/campaigns/{id}/test

Sends the campaign as saved to the account owner's address, subject prefixed with [Test]. Nobody else gets it. It counts toward the plan's emails.

MCP toolsend_test_emailKeyFull accessReaches outside MailCheap

Parameter Description

idrequired

path · string

The campaign's ID

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/test" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Schedule a campaign

POST/api/v1/campaigns/{id}/schedule

Schedules a draft to send by itself at a time within a year. It goes out without asking again, unless unschedule_campaign runs first. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. Plan limits and pre-send checks run now and again when it goes out. MailCheap Cloud paces a send by the volume its account has proven: its largest campaign of the last 60 days whose bounces and complaints stayed under the pause level, counted a day after it went out. A send, with what the account's other sends still have to send or sent in the last 24 hours, goes at full speed up to 200 emails, or that volume times 2 on the first day of the account's 30-day warm-up, rising to 5 by its last day and after it. A bigger send goes out over 4 hours plus 4 for each time it doubles that, 72 at most (spreadHours, sendingUntil); a resume keeps the pace, each step of send_campaign_to_more gets its own. Contacts never mailed before go in steps: a slice first, the rest 3 hours after it if the slice's bounces and complaints stay under the pause level. Past 2.00% hard bounces (at least 5) or 0.08% complaints (at least 2), the campaign pauses with pauseCode high_rates, or first_send_slice for a slice, and resume_campaign sends the rest. Past 5.00% (at least 10) or 0.30% (at least 3), the account is blocked. On MailCheap Cloud an automated check reads the content first: an issue that looks clearly harmful (phishing, malware, scams, explicit content) pauses with pauseCode content_review until MailCheap reviews it.

MCP toolschedule_campaignKeyFull accessCan't be undoneSafe to repeatReaches outside MailCheap

Parameter	Description
`id`required path · string The campaign's ID	The campaign's ID
`scheduledAt`required body · string ISO 8601 date and time, e.g. 2026-10-20T09:00:00Z, at least a minute ahead	ISO 8601 date and time, e.g. 2026-10-20T09:00:00Z, at least a minute ahead
`audienceLimit` body · integer Send to this many contacts at most, the most engaged first. The rest can follow with send_campaign_to_more.	Send to this many contacts at most, the most engaged first. The rest can follow with send_campaign_to_more.
`segment` 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.	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.

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/schedule" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt":"2026-10-20T09:00:00Z"}'

Cancel a scheduled send

POST/api/v1/campaigns/{id}/unschedule

Turns a scheduled campaign back into a draft, so it doesn't go out.

MCP toolunschedule_campaignKeyFull accessSafe to repeat

Parameter Description

idrequired

path · string

The campaign's ID

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/unschedule" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Send a campaign now

POST/api/v1/campaigns/{id}/send

Sends a draft or scheduled campaign now to the newsletter's active contacts, or its segment's, most engaged first. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. A campaign that is already sending or sent answers conflict, so a retry never sends twice. Plan limits, the from address, the postal address and the email size are checked first. MailCheap Cloud paces a send by the volume its account has proven: its largest campaign of the last 60 days whose bounces and complaints stayed under the pause level, counted a day after it went out. A send, with what the account's other sends still have to send or sent in the last 24 hours, goes at full speed up to 200 emails, or that volume times 2 on the first day of the account's 30-day warm-up, rising to 5 by its last day and after it. A bigger send goes out over 4 hours plus 4 for each time it doubles that, 72 at most (spreadHours, sendingUntil); a resume keeps the pace, each step of send_campaign_to_more gets its own. Contacts never mailed before go in steps: a slice first, the rest 3 hours after it if the slice's bounces and complaints stay under the pause level. Past 2.00% hard bounces (at least 5) or 0.08% complaints (at least 2), the campaign pauses with pauseCode high_rates, or first_send_slice for a slice, and resume_campaign sends the rest. Past 5.00% (at least 10) or 0.30% (at least 3), the account is blocked. On MailCheap Cloud an automated check reads the content first: an issue that looks clearly harmful (phishing, malware, scams, explicit content) pauses with pauseCode content_review until MailCheap reviews it.

MCP toolsend_campaignKeyFull accessCan't be undoneReaches outside MailCheap

Parameter Description

idrequired

path · string

The campaign's ID

audienceLimit

body · integer

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

segment

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.

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/send" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Send a campaign to more contacts

POST/api/v1/campaigns/{id}/send-more

Sends a sent campaign to contacts who haven't received it yet, the next most engaged first: a send in steps. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. Each call starts a new step, so check get_campaign_report before calling it again; while a step is still sending it answers conflict. MailCheap Cloud paces a send by the volume its account has proven: its largest campaign of the last 60 days whose bounces and complaints stayed under the pause level, counted a day after it went out. A send, with what the account's other sends still have to send or sent in the last 24 hours, goes at full speed up to 200 emails, or that volume times 2 on the first day of the account's 30-day warm-up, rising to 5 by its last day and after it. A bigger send goes out over 4 hours plus 4 for each time it doubles that, 72 at most (spreadHours, sendingUntil); a resume keeps the pace, each step of send_campaign_to_more gets its own. Contacts never mailed before go in steps: a slice first, the rest 3 hours after it if the slice's bounces and complaints stay under the pause level. Past 2.00% hard bounces (at least 5) or 0.08% complaints (at least 2), the campaign pauses with pauseCode high_rates, or first_send_slice for a slice, and resume_campaign sends the rest. Past 5.00% (at least 10) or 0.30% (at least 3), the account is blocked. On MailCheap Cloud an automated check reads the content first: an issue that looks clearly harmful (phishing, malware, scams, explicit content) pauses with pauseCode content_review until MailCheap reviews it.

MCP toolsend_campaign_to_moreKeyFull accessCan't be undoneReaches outside MailCheap

Parameter Description

idrequired

path · string

The campaign's ID

additional

body · integer

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

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/send-more" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"additional":2000}'

Pause a campaign

POST/api/v1/campaigns/{id}/pause

Stops a campaign that is sending. Emails already sent stay sent; the rest wait until resume_campaign.

MCP toolpause_campaignKeyFull accessSafe to repeat

Parameter Description

idrequired

path · string

The campaign's ID

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/pause" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Resume a paused campaign

POST/api/v1/campaigns/{id}/resume

Sends the rest of a paused campaign. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. The plan limits and the account's state are checked again first. Resumed after a high_rates or first_send_slice pause, only the block level stops it again. A content_review or content_rejected pause answers conflict: only MailCheap's review starts it.

MCP toolresume_campaignKeyFull accessCan't be undoneReaches outside MailCheap

Parameter Description

idrequired

path · string

The campaign's ID

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/resume" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Update a campaign's archive page

PATCH/api/v1/campaigns/{id}/archive

Changes the path of a campaign's archive page (/p/<slug>), or pins a sent issue to the top of the archive. Works on sent campaigns too.

MCP toolupdate_campaign_archiveKeyFull accessSafe to repeat

Parameter Description

idrequired

path · string

The campaign's ID

slug

body · string

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

pinned

body · boolean

Pinned issues lead the archive

Request

curl -X PATCH "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/archive" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pinned":true}'

Preview the list cleanup of a send

GET/api/v1/campaigns/{id}/cleanup-preview

Counts what the newsletter's list cleanup would do if the campaign went out now: issues sent, last-chance emails instead, contacts still waiting to answer one, and contacts made dormant. Reads the whole list, so it can take a few seconds.

MCP toolpreview_campaign_cleanupKeyFull accessRead-onlySafe to repeat

Parameter Description

idrequired

path · string

The campaign's ID

audienceLimit

query · integer

Count for a send capped at this many contacts

includeRanks

query · boolean

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

Request

curl "https://newsletter.adityakhare.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/cleanup-preview" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Contacts

Search, signups, imports with checks, status changes, deletes and exports.

List contacts

GET/api/v1/contacts

Lists contacts, newest signups first, 50 a page, with their first name, tags and field values. Filter by newsletter, status, segment, tag or the start of the email address; pass nextCursor back as cursor for the next page. counts has every status for the same filters.

MCP toollist_contactsKeyFull accessRead-onlySafe to repeat

Parameter	Description
`newsletter` query · string Only this newsletter's: its ID or slug. Default: every newsletter.	Only this newsletter's: its ID or slug. Default: every newsletter.
`status` query · "active" \| "pending" \| "unsubscribed" \| "bounced" \| "complained" \| "dormant" Only contacts with this status	Only contacts with this status
`segment` 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.	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.
`tag` query · string Only contacts with this tag	Only contacts with this tag
`search` query · string Contacts whose email starts with this	Contacts whose email starts with this
`limit` query · integer Contacts per page, 50 by default, 100 at most	Contacts per page, 50 by default, 100 at most
`cursor` query · string nextCursor from the previous page	nextCursor from the previous page

Request

curl "https://newsletter.adityakhare.com/api/v1/contacts?status=active&search=jane" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Get a contact

GET/api/v1/contacts/{id}

Gets one contact by ID or email address, with its status, first name, tags, field values, dates and engagement.

MCP toolget_contactKeyFull accessRead-onlySafe to repeat

Parameter Description

idrequired

path · string

The contact's ID or email address

newsletter

query · string

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

Request

curl "https://newsletter.adityakhare.com/api/v1/contacts/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Add a contact

POST/api/v1/contacts

Signs someone up, like the archive's form: they get the welcome email, or the confirmation email when the newsletter asks new subscribers to confirm. Signing up again keeps the contact as it is unless resubscribe is true. Works with signups only keys, for website forms. Signups and confirmation emails keep coming in over the plan's limits; welcome emails count toward the month's emails and are skipped once they're used up, never sent later (get_billing's usage.welcomeEmailsPaused). A misspelled domain (gmial.com) answers validation_failed with the address it was likely meant to be; spam trap addresses, domains that can't receive email, and addresses MailCheap knows can't receive email (they hard bounced or hit a spam trap, from any sender on MailCheap) answer validation_failed too.

MCP tooladd_contactKeyFull access or signups onlyReaches outside MailCheap

Parameter	Description
`newsletter` body · string The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.	The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.
`email`required body · string The subscriber's email address	The subscriber's email address
`firstName` 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.	Their first name, which {{first_name}} prints in emails. For a contact who signs up again, only saved if they had none.
`tags` body · string[] Tags to add, lowercase, no commas. A contact who signs up again keeps theirs and gets these too.	Tags to add, lowercase, no commas. A contact who signs up again keeps theirs and gets these too.
`fields` 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.	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.
`source` body · string Where they signed up, e.g. website. Default: api.	Where they signed up, e.g. website. Default: api.
`resubscribe` 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.	Bring back a contact who unsubscribed or went dormant. Bounced and complained addresses never come back, nor does a contact deleted after it unsubscribed.
`ip` body · string The visitor's IP address: one visitor gets 5 signups in 10 minutes	The visitor's IP address: one visitor gets 5 signups in 10 minutes

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/contacts" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","source":"website"}'

Update a contact

PATCH/api/v1/contacts/{id}/details

Changes a contact's first name, field values or tags. Send only what changes: tags replace the contact's own (tag_contacts and untag_contacts add or remove some), fields only change the keys given. update_contact_status changes the status.

MCP toolupdate_contactKeyFull accessSafe to repeat

Parameter	Description
`id`required path · string The contact's ID or email address	The contact's ID or email address
`newsletter` body · string The newsletter's ID or slug, needed for an email address that is a contact of several newsletters	The newsletter's ID or slug, needed for an email address that is a contact of several newsletters
`firstName` body · string \| null The first name {{first_name}} prints in emails. null or "" removes it.	The first name {{first_name}} prints in emails. null or "" removes it.
`tags` body · string[] The contact's tags, replacing the ones it has. [] removes them all.	The contact's tags, replacing the ones it has. [] removes them all.
`fields` 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.	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.

Request

curl -X PATCH "https://newsletter.adityakhare.com/api/v1/contacts/6650f1c2e9b1d4a012345678/details" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","tags":["vip","podcast"],"fields":{"company":"Acme"}}'

Change a contact's status

PATCH/api/v1/contacts/{id}

Sets a contact's status to active, dormant or unsubscribed. active brings back a dormant contact, resubscribes one who unsubscribed, or makes a pending one active without the confirmation email; dormant stops issues to an active contact without unsubscribing them; unsubscribed stops every email. Resubscribing and making a pending contact active need consent: true, your word that the person asked for it. Someone who unsubscribed can only become active. Bounced and complained contacts never change, and an address the account or MailCheap won't email (it bounced, complained or hit a spam trap) can't become active. No email goes out.

MCP toolupdate_contact_statusKeyFull accessCan't be undoneSafe to repeat

Parameter	Description
`id`required path · string The contact's ID or email address	The contact's ID or email address
`newsletter` body · string The newsletter's ID or slug, needed for an email address that is a contact of several newsletters	The newsletter's ID or slug, needed for an email address that is a contact of several newsletters
`status`required body · "active" \| "dormant" \| "unsubscribed" active, dormant or unsubscribed	active, dormant or unsubscribed
`consent` body · boolean true when the person asked for it: needed to resubscribe someone who unsubscribed, or to make a pending contact active	true when the person asked for it: needed to resubscribe someone who unsubscribed, or to make a pending contact active

Request

curl -X PATCH "https://newsletter.adityakhare.com/api/v1/contacts/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"dormant"}'

Tag contacts

POST/api/v1/contacts/tag

Adds tags to contacts, keeping the tags they have: a list of contacts, or every contact a filter picks (a segment, a status, a tag, the start of the address). Segments can then pick them by tag (field tag, op has).

MCP tooltag_contactsKeyFull accessSafe to repeat

Parameter	Description
`newsletter` body · string The newsletter's ID or slug, needed for an email address that is a contact of several newsletters	The newsletter's ID or slug, needed for an email address that is a contact of several newsletters
`contacts` body · string[] Contact IDs or email addresses, 1,000 at most. An address matches its contact in every newsletter unless newsletter is given.	Contact IDs or email addresses, 1,000 at most. An address matches its contact in every newsletter unless newsletter is given.
`filter` body · object Instead of contacts: every contact of the newsletter these pick, like list_contacts' filters. Needs newsletter.	Instead of contacts: every contact of the newsletter these pick, like list_contacts' filters. Needs newsletter.
`filter.segment` 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.	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.
`filter.status` body · "active" \| "pending" \| "unsubscribed" \| "bounced" \| "complained" \| "dormant" Only contacts with this status	Only contacts with this status
`filter.tag` body · string Only contacts with this tag	Only contacts with this tag
`filter.search` body · string Contacts whose email starts with this	Contacts whose email starts with this
`tags`required body · string[] Tags, 10 at most. Tags are lowercase.	Tags, 10 at most. Tags are lowercase.

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/contacts/tag" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags":["vip"],"contacts":["jane@example.com"]}'

Untag contacts

POST/api/v1/contacts/untag

Takes tags off contacts, a list of them or every contact a filter picks, like tag_contacts. Other tags stay.

MCP tooluntag_contactsKeyFull accessSafe to repeat

Parameter	Description
`newsletter` body · string The newsletter's ID or slug, needed for an email address that is a contact of several newsletters	The newsletter's ID or slug, needed for an email address that is a contact of several newsletters
`contacts` body · string[] Contact IDs or email addresses, 1,000 at most. An address matches its contact in every newsletter unless newsletter is given.	Contact IDs or email addresses, 1,000 at most. An address matches its contact in every newsletter unless newsletter is given.
`filter` body · object Instead of contacts: every contact of the newsletter these pick, like list_contacts' filters. Needs newsletter.	Instead of contacts: every contact of the newsletter these pick, like list_contacts' filters. Needs newsletter.
`filter.segment` 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.	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.
`filter.status` body · "active" \| "pending" \| "unsubscribed" \| "bounced" \| "complained" \| "dormant" Only contacts with this status	Only contacts with this status
`filter.tag` body · string Only contacts with this tag	Only contacts with this tag
`filter.search` body · string Contacts whose email starts with this	Contacts whose email starts with this
`tags`required body · string[] Tags, 10 at most. Tags are lowercase.	Tags, 10 at most. Tags are lowercase.

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/contacts/untag" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags":["vip"],"contacts":["jane@example.com"]}'

Delete a contact

DELETE/api/v1/contacts/{id}

Deletes a contact from its newsletter, with its dates and engagement. It can't be undone. For a contact who unsubscribed, bounced or complained, MailCheap keeps a hash of the address so the newsletter never emails it again: import_contacts leaves it out, and add_contact or a signup form adds it back with that status. Any other contact can be added again like a new one.

MCP tooldelete_contactKeyFull accessCan't be undoneSafe to repeat

Parameter Description

idrequired

path · string

The contact's ID or email address

newsletter

query · string

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

Request

curl -X DELETE "https://newsletter.adityakhare.com/api/v1/contacts/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Import contacts

POST/api/v1/contacts/import

Queues up to 1000 contacts per call for a background import, with the same checks as the dashboard's CSV import: invalid, misspelled (gmial.com…), spam trap, role (info@, support@…), throwaway, duplicate and suppressed addresses, undeliverable ones (MailCheap knows they can't receive email: they hard bounced or hit a spam trap, from any sender on MailCheap), and addresses on domains that can't receive email, are left out and counted. consent must be true: "These people agreed to receive my emails". Existing contacts keep their status unless a row gives a stricter one (unsubscribed, bounced, complained), which is final. No welcome emails go out. For more rows, send the next chunk with the importId of the first, one call after the other: chunks are processed in the order they arrive, 250,000 rows at most per import. Answers right away with the import's status and counts so far; get_import shows them as it goes, and with total set, status turns done once every row is in.

MCP toolimport_contactsKeyFull accessCan't be undoneSafe to repeat

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/contacts/import" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"consent":true,"contacts":[{"email":"jane@example.com","subscribedAt":"2025-03-01T00:00:00Z"},{"email":"sam@example.com","status":"unsubscribed"}]}'

Get an import

GET/api/v1/contacts/imports/{id}

An import's status and counts as its rows go in: processing while they wait for the background job or for more rows, then done, or failed with the reason in error.

MCP toolget_importKeyFull accessRead-onlySafe to repeat

Parameter Description

Parameter	Description
`id`required path · string The importId import_contacts answered with	The importId import_contacts answered with

idrequired

path · string

The importId import_contacts answered with

Request

curl "https://newsletter.adityakhare.com/api/v1/contacts/imports/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

List imports

GET/api/v1/contacts/imports

The latest imports, newest first, with their status and counts.

MCP toollist_importsKeyFull accessRead-onlySafe to repeat

Parameter Description

newsletter

query · string

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

limit

query · integer

How many, 5 by default

Request

curl "https://newsletter.adityakhare.com/api/v1/contacts/imports" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Export contacts

GET/api/v1/contacts/export

Makes a CSV download link for the contacts matching the filters, valid for an hour, no API key needed to open it. The columns go back in through the import as they are.

MCP toolexport_contactsKeyFull accessRead-onlySafe to repeat

Parameter	Description
`newsletter` query · string Only this newsletter's: its ID or slug. Default: every newsletter.	Only this newsletter's: its ID or slug. Default: every newsletter.
`status` query · "active" \| "pending" \| "unsubscribed" \| "bounced" \| "complained" \| "dormant" Only contacts with this status	Only contacts with this status
`segment` 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.	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.
`tag` query · string Only contacts with this tag	Only contacts with this tag
`search` query · string Contacts whose email starts with this	Contacts whose email starts with this

Request

curl "https://newsletter.adityakhare.com/api/v1/contacts/export?status=active" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

List tags

GET/api/v1/contacts/tags

Lists the tags contacts have, most used first, with how many contacts have each (200 at most).

MCP toollist_contact_tagsKeyFull accessRead-onlySafe to repeat

Parameter Description

newsletter

query · string

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

Request

curl "https://newsletter.adityakhare.com/api/v1/contacts/tags" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

List contact fields

GET/api/v1/contacts/fields

Lists the account's own contact fields, shared by its newsletters: their key (for fields on contacts, segments as fields.<key>, and CSV columns), name and type. Every contact also has a first name and tags.

MCP toollist_contact_fieldsKeyFull accessRead-onlySafe to repeat

Request

curl "https://newsletter.adityakhare.com/api/v1/contacts/fields" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Create a contact field

POST/api/v1/contacts/fields

Adds a field contacts can hold, like a company or a birthday, 20 at most. Its key comes from the name: "Company size" becomes company_size.

MCP toolcreate_contact_fieldKeyFull access

Parameter Description

Parameter	Description
`label`required body · string The field's name, 40 characters at most	The field's name, 40 characters at most
`type`required body · "text" \| "number" \| "date" text, number or date	text, number or date

labelrequired

body · string

The field's name, 40 characters at most

typerequired

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

text, number or date

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/contacts/fields" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Company","type":"text"}'

Delete a contact field

DELETE/api/v1/contacts/fields/{key}

Deletes one of the account's contact fields. Contacts keep their values, hidden, and get them back if a field with the same key is added again. A segment using it answers conflict: change the segment first.

MCP tooldelete_contact_fieldKeyFull accessCan't be undoneSafe to repeat

Parameter Description

Parameter	Description
`key`required path · string The field's key, from list_contact_fields	The field's key, from list_contact_fields

keyrequired

path · string

The field's key, from list_contact_fields

Request

curl -X DELETE "https://newsletter.adityakhare.com/api/v1/contacts/fields/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Segments

Saved conditions that pick some of a newsletter's contacts by engagement, signup date, source or address, to send campaigns to them only.

List segments

GET/api/v1/segments

Lists segments, oldest first, with their conditions in words and how many active contacts each picks now.

MCP toollist_segmentsKeyFull accessRead-onlySafe to repeat

Parameter Description

newsletter

query · string

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

Request

curl "https://newsletter.adityakhare.com/api/v1/segments" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Get a segment

GET/api/v1/segments/{id}

Gets one segment with its conditions and how many active contacts it picks now.

MCP toolget_segmentKeyFull accessRead-onlySafe to repeat

Parameter Description

idrequired

path · string

The segment's ID

Request

curl "https://newsletter.adityakhare.com/api/v1/segments/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Count a segment's contacts

POST/api/v1/segments/count

Counts the active contacts some conditions would pick, without saving anything: try them before create_segment.

MCP toolcount_segmentKeyFull accessRead-onlySafe to repeat

Parameter	Description
`newsletter` body · string The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.	The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.
`match` body · "all" \| "any" all: contacts meeting every condition (the default). any: contacts meeting at least one.	all: contacts meeting every condition (the default). any: contacts meeting at least one.
`conditions`required body · object[] The conditions, 10 at most. Dates count back from each send, so "within 30 days" moves with time.	The conditions, 10 at most. Dates count back from each send, so "within 30 days" moves with time.
`conditions[].field`required 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).	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).
`conditions[].op`required 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.	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.
`conditions[].value` 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.	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.

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/segments/count" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conditions":[{"field":"opened","op":"within","value":30}]}'

Create a segment

POST/api/v1/segments

Saves conditions that pick some of a newsletter's contacts, to send campaigns to them only (segment on update_campaign, send_campaign or schedule_campaign). Contacts join and leave it as they meet the conditions.

MCP toolcreate_segmentKeyFull access

Parameter	Description
`newsletter` body · string The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.	The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.
`name`required body · string The segment's name, 60 characters at most	The segment's name, 60 characters at most
`match` body · "all" \| "any" all: contacts meeting every condition (the default). any: contacts meeting at least one.	all: contacts meeting every condition (the default). any: contacts meeting at least one.
`conditions`required body · object[] The conditions, 10 at most. Dates count back from each send, so "within 30 days" moves with time.	The conditions, 10 at most. Dates count back from each send, so "within 30 days" moves with time.
`conditions[].field`required 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).	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).
`conditions[].op`required 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.	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.
`conditions[].value` 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.	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.

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/segments" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Engaged","conditions":[{"field":"opened","op":"within","value":30}]}'

Update a segment

PATCH/api/v1/segments/{id}

Renames a segment or changes its conditions. Send only what changes; conditions replace the old ones. Campaigns going to it, scheduled ones included, use the new conditions when they go out.

MCP toolupdate_segmentKeyFull accessSafe to repeat

Parameter	Description
`id`required path · string The segment's ID	The segment's ID
`name` body · string The segment's name, 60 characters at most	The segment's name, 60 characters at most
`match` body · "all" \| "any" all: contacts meeting every condition (the default). any: contacts meeting at least one.	all: contacts meeting every condition (the default). any: contacts meeting at least one.
`conditions` body · object[] The conditions, 10 at most. Dates count back from each send, so "within 30 days" moves with time.	The conditions, 10 at most. Dates count back from each send, so "within 30 days" moves with time.
`conditions[].field`required 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).	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).
`conditions[].op`required 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.	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.
`conditions[].value` 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.	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.

Request

curl -X PATCH "https://newsletter.adityakhare.com/api/v1/segments/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Engaged this quarter","conditions":[{"field":"opened","op":"within","value":90}]}'

Delete a segment

DELETE/api/v1/segments/{id}

Deletes a segment. Its contacts stay as they are. A scheduled, sending or paused campaign going to it answers conflict: change who it goes to first. Drafts going to it can't be sent until they get another segment or none.

MCP tooldelete_segmentKeyFull accessCan't be undoneSafe to repeat

Parameter Description

idrequired

path · string

The segment's ID

Request

curl -X DELETE "https://newsletter.adityakhare.com/api/v1/segments/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Domains

Own sending domains with their DNS records, and the shared address.

List domains

GET/api/v1/domains

Lists the account's own sending domains with their DNS records and status as last checked, and each newsletter's shared address (hello@<slug>.<shared domain>), which works with no setup.

MCP toollist_domainsKeyFull accessRead-onlySafe to repeat

Request

curl "https://newsletter.adityakhare.com/api/v1/domains" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Add a domain

POST/api/v1/domains

Adds a domain to send from, in the account's own tenant at the email provider: emails are signed with DKIM and bounces return to a subdomain of it (rp.<domain> on PostShiba, bounce.<domain> on Amazon SES). The answer lists the DNS records to add; check_domain reads them once they're in. Newsletters can send from it once it's verified.

MCP tooladd_domainKeyFull accessReaches outside MailCheap

Parameter Description

Parameter	Description
`domain`required 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.	e.g. example.com. An address or a link works too: jane@example.com and https://www.example.com/about both add example.com.
`archiveHost` 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>.	Used when the domain's setup lists an archive step: the subdomain for the archive, tracked links and unsubscribe links. Default: news.<domain>.

domainrequired

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.

archiveHost

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

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/domains" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

Check a domain's DNS records

POST/api/v1/domains/{id}/check

Asks the email provider and DNS again whether the domain's records are in, and looks up its DMARC record or its parent domain's. On PostShiba, a check within a minute of the last one answers what that one found. When its setup lists an archive step, the newsletter sending from the domain moves its archive and links to that subdomain once it points at MailCheap.

MCP toolcheck_domainKeyFull accessSafe to repeatReaches outside MailCheap

Parameter Description

Parameter	Description
`id`required path · string The domain's ID	The domain's ID

idrequired

path · string

The domain's ID

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/domains/6650f1c2e9b1d4a012345678/check" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Remove a domain

DELETE/api/v1/domains/{id}

Removes a domain from the email provider, and its archive subdomain from MailCheap when its setup lists one. Newsletters on it can't send until they move to another address. Refused while a campaign from it is sending, paused or scheduled. Adding it again needs new DNS records.

MCP toolremove_domainKeyFull accessCan't be undoneSafe to repeatReaches outside MailCheap

Parameter Description

Parameter	Description
`id`required path · string The domain's ID	The domain's ID

idrequired

path · string

The domain's ID

Request

curl -X DELETE "https://newsletter.adityakhare.com/api/v1/domains/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Images

Pictures for campaign content, on MailCheap's CDN, kept in the account's library to use again.

List images

GET/api/v1/images

Lists the images uploaded to the account, newest first, 50 a page, so a campaign can use one again without uploading it twice. Pass nextCursor back as cursor for the next page.

MCP toollist_imagesKeyFull accessRead-onlySafe to repeat

Parameter Description

Parameter	Description
`limit` query · integer Images per page, 50 by default, 100 at most	Images per page, 50 by default, 100 at most
`cursor` query · string nextCursor from the previous page	nextCursor from the previous page

limit

query · integer

Images per page, 50 by default, 100 at most

cursor

query · string

nextCursor from the previous page

Request

curl "https://newsletter.adityakhare.com/api/v1/images?limit=20" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Upload an image

POST/api/v1/images

Stores a PNG, JPEG, GIF or WebP image under 4 MB on MailCheap's CDN and returns its URL for campaign content. Send the file as base64 (under about 3 MB, since requests stop at 4.5 MB) or an https:// link MailCheap downloads. The URL never changes: sent emails keep pointing at it. list_images finds images uploaded before.

MCP toolupload_imageKeyFull accessReaches outside MailCheap

Parameter	Description
`base64` body · string The image file, base64 encoded; a data: URL works too	The image file, base64 encoded; a data: URL works too
`url` body · string An https:// link to the image	An https:// link to the image
`fileName` body · string Used in the stored file's name	Used in the stored file's name
`contentType` body · string The file's type, checked against its first bytes	The file's type, checked against its first bytes

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/images" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/cover.png"}'

API keys

Keys for the REST API and MCP.

List API keys

GET/api/v1/api-keys

Lists the account's API keys, revoked ones included, with their level and when they were last used. Keys themselves are never shown again.

MCP toollist_api_keysKeyFull accessRead-onlySafe to repeat

Request

curl "https://newsletter.adityakhare.com/api/v1/api-keys" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Create an API key

POST/api/v1/api-keys

Creates an API key and returns it once; only its hash is stored. full can do everything a full key can, including creating more keys; signups can only add contacts, for keys that end up in website code. An account has up to 20 active keys: one more answers conflict until one is revoked.

MCP toolcreate_api_keyKeyFull access

Parameter Description

namerequired

body · string

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

levelrequired

body · "full" | "signups"

full or signups

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/api-keys" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Website signups","level":"signups"}'

Revoke an API key

DELETE/api/v1/api-keys/{id}

Revokes an API key for good: requests with it answer unauthorized from now on. A key can revoke itself.

MCP toolrevoke_api_keyKeyFull accessCan't be undoneSafe to repeat

Parameter Description

idrequired

path · string

The API key's ID

Request

curl -X DELETE "https://newsletter.adityakhare.com/api/v1/api-keys/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

List connected apps

GET/api/v1/connected-apps

Lists the apps connected to the account with OAuth, such as ChatGPT, Claude and Grok Bot, with when they were connected and last used. Each one has full access, like a full access API key.

MCP toollist_connected_appsKeyFull accessRead-onlySafe to repeat

Request

curl "https://newsletter.adityakhare.com/api/v1/connected-apps" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Disconnect an app

DELETE/api/v1/connected-apps/{id}

Disconnects an app connected with OAuth: its tokens stop working at once, and it has to ask for access again to come back. An app can disconnect itself.

MCP toolrevoke_connected_appKeyFull accessCan't be undoneSafe to repeat

Parameter Description

idrequired

path · string

The connected app's ID

Request

curl -X DELETE "https://newsletter.adityakhare.com/api/v1/connected-apps/6650f1c2e9b1d4a012345678" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Billing

Plan, usage and links to Stripe to change plan.

Get the plan and usage

GET/api/v1/billing

The account's plan, subscription status and this month's usage against the plan's limits, with every plan on sale for comparison. Works without an active plan. A self-hosted server has no billing and answers billing_off.

MCP toolget_billingKeyFull accessRead-onlySafe to repeat

Request

curl "https://newsletter.adityakhare.com/api/v1/billing" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Change plan

POST/api/v1/billing/change-plan

Returns a Stripe page where the account owner picks up the change: Checkout without a paid plan (on a free plan too: the paid plan takes over), the Customer Portal's confirmation page with one. Nothing changes until they confirm there. Give the URL to the user. A self-hosted server has no billing and answers billing_off.

MCP toolchange_planKeyFull accessReaches outside MailCheap

Parameter Description

planrequired

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

starter, growth, pro, scale or max

interval

body · "month" | "year"

month (default) or year, which costs 10 months

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/billing/change-plan" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"growth","interval":"year"}'

Open the billing portal

POST/api/v1/billing/portal

Returns a Stripe Customer Portal link for the account owner: payment method, invoices, plan changes and cancellation. A self-hosted server has no billing and answers billing_off.

MCP toolopen_billing_portalKeyFull accessReaches outside MailCheap

Request

curl -X POST "https://newsletter.adityakhare.com/api/v1/billing/portal" \
  -H "Authorization: Bearer $MAILCHEAP_API_KEY"

Parameter	Description
`newsletter` body · string The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.	The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest.
`consent`required body · boolean Must be true: These people agreed to receive my emails. Bought or scraped lists aren't allowed.	Must be true: These people agreed to receive my emails. Bought or scraped lists aren't allowed.
`contacts`required body · object[] The rows, 1000 at most	The rows, 1000 at most
`contacts[].email`required body · string Invalid addresses are left out and counted	Invalid addresses are left out and counted
`contacts[].status` body · "active" \| "dormant" \| "unsubscribed" \| "bounced" \| "complained" active (default), dormant, unsubscribed, bounced or complained	active (default), dormant, unsubscribed, bounced or complained
`contacts[].subscribedAt` body · string When they signed up, ISO 8601	When they signed up, ISO 8601
`contacts[].emailsReceived` body · number Emails they got on the previous platform	Emails they got on the previous platform
`contacts[].openRate` body · number 0 to 1, from the previous platform: sends reach the most engaged first	0 to 1, from the previous platform: sends reach the most engaged first
`contacts[].clickRate` body · number 0 to 1, from the previous platform	0 to 1, from the previous platform
`contacts[].lastOpenAt` body · string Their last open on the previous platform, ISO 8601: segments on opens use it	Their last open on the previous platform, ISO 8601: segments on opens use it
`contacts[].lastClickAt` body · string Their last click on the previous platform, ISO 8601	Their last click on the previous platform, ISO 8601
`contacts[].opens` body · integer How many emails they opened on the previous platform	How many emails they opened on the previous platform
`contacts[].clicks` body · integer How many emails they clicked on the previous platform	How many emails they clicked on the previous platform
`contacts[].firstName` body · string Their first name, replacing the contact's	Their first name, replacing the contact's
`contacts[].tags` body · string[] Tags added to the contact's own	Tags added to the contact's own
`contacts[].fields` body · object Values for the account's own fields, by key: values that don't fit the field's type are left out	Values for the account's own fields, by key: values that don't fit the field's type are left out
`importId` body · string The importId of the first chunk, to add rows to the same import	The importId of the first chunk, to add rows to the same import
`total` body · integer With the first chunk: the rows the whole import sends, so its status turns done once they're all processed	With the first chunk: the rows the whole import sends, so its status turns done once they're all processed
`duplicates` body · integer Duplicates you removed before sending, counted in the import's report	Duplicates you removed before sending, counted in the import's report