# MailCheap API and MCP reference Everything a MailCheap customer does in the dashboard works through the REST API and the MCP server. Both run the same actions as the dashboard, with the same plan limits, sender rules, pre-send checks, paused accounts and first-send steps. ## Authentication Create an API key on the dashboard's API keys page and send it as `Authorization: Bearer ` to https://news.carolekorngold.com/api/v1 or to the MCP server at https://news.carolekorngold.com/mcp. - Full access keys can do everything below, including creating more keys. Keep them on a server or in your AI assistant's settings. - Signups only keys can only add contacts (`POST /api/v1/contacts`, MCP tool `add_contact`), for signup forms in website code. That endpoint also answers browsers (CORS). - Every key gets 300 requests a minute across REST and MCP, and some actions have their own hourly limit. Over it, the answer is 429 rate_limited. - Keys are stored hashed and shown once. Revoked keys answer 401 unauthorized. - The MCP server also takes OAuth access tokens, for apps such as ChatGPT, Claude and Grok Bot: the user signs in to MailCheap and allows the app, which then has full access. Discovery starts at https://news.carolekorngold.com/.well-known/oauth-protected-resource/mcp. ## Errors Every error answers `{ "error": { "code": "…", "message": "…" } }`. MCP tools answer the same object in an error result. Codes never change meaning: - `unauthorized` (401): The API key is missing, malformed, unknown or revoked. - `forbidden` (403): The key's level doesn't allow this action: a signups only key can only add contacts. - `not_found` (404): The newsletter, campaign, contact, domain or key isn't in this account. - `validation_failed` (400): The input doesn't match the schema or breaks a rule. The message names the field. - `conflict` (409): The resource's state doesn't allow it, e.g. sending a campaign that is already sending or sent. Retrying won't help. - `rate_limited` (429): Too many requests with this key. Wait a minute and retry. - `subscription_required` (402): The account has no active plan. - `billing_off` (404): The server is self-hosted without billing: every account has every feature, without plan limits. - `plan_limit_emails` (402): The send needs more emails than the plan has left this month. - `plan_limit_subscribers` (402): The account has more active subscribers than its plan allows. - `account_blocked` (403): The account is blocked after spam signals (bounce or complaint rates, a spam trap, the email provider) or by an admin. Nothing is sent, and only reads, pausing, unscheduling, revoking access and billing work until an admin unblocks it. - `sender_not_allowed` (422): The from address is neither the newsletter's shared address nor on a verified domain of this account. - `send_check_failed` (422): A pre-send check failed: no postal address, subject or content, or the email is over 100 KB. - `no_recipients` (422): Nobody is left to send to. - `sending_disabled` (503): Sending is turned off on this server. - `unavailable` (503): A service the action needs isn't configured or didn't answer. Retry later. - `internal_error` (500): Something failed on MailCheap's side. Sending a campaign that is already sending or sent answers `conflict`, so retrying a send never sends twice. ## MCP The MCP server speaks Streamable HTTP at https://news.carolekorngold.com/mcp, without sessions. Each endpoint below is one tool with the same name, input and output; its annotations tell clients whether it's read-only, can't be undone, is safe to repeat or reaches outside MailCheap. The send tools can't be undone: ask the user before calling them. ### ChatGPT 1. Turn on developer mode: Settings › Apps › Advanced settings › Developer mode. 2. Go to Settings › Apps › Create. Name it MailCheap, enter https://news.carolekorngold.com/mcp as the MCP server URL and pick OAuth as the authentication. 3. Click Scan Tools, sign in to MailCheap in the window that opens and click Allow. Then click Create. 4. In a chat, pick MailCheap from the + menu, or name it in your message. Developer mode is on ChatGPT on the web, for Business, Enterprise and Edu workspaces, where an admin may have to allow it first. On Pro, ChatGPT only uses the read-only tools for now. ### Claude 1. Go to Customize › Connectors and click Add custom connector. 2. Enter https://news.carolekorngold.com/mcp. If Claude asks how it identifies itself, keep Use Claude's published identity. Click Add. 3. Click Connect, sign in to MailCheap and click Allow. 4. The connector works in claude.ai, Claude Desktop and the mobile apps. Turn it on or off in a chat from + › Connectors. On Team and Enterprise plans, an owner adds it once in Organization settings › Connectors › Add › Custom › Web, then each member clicks Connect under Customize › Connectors. The Free plan has one custom connector. ### Grok Bot 1. In a chat, ask Grok Bot to add the custom MCP server https://news.carolekorngold.com/mcp. 2. Sign in to MailCheap when it asks, and click Allow. ### Claude Code Terminal: ``` claude mcp add --transport http --scope user mailcheap https://news.carolekorngold.com/mcp \ --header "Authorization: Bearer $MAILCHEAP_API_KEY" ``` The shell puts the key in Claude Code's settings when the command runs. --scope user makes the server available in every project; run /mcp in Claude Code to check it's connected. ### Codex ~/.codex/config.toml: ``` [mcp_servers.mailcheap] url = "https://news.carolekorngold.com/mcp" bearer_token_env_var = "MAILCHEAP_API_KEY" ``` Codex reads the key from MAILCHEAP_API_KEY each time it starts, so export it in your shell profile. The same server from the terminal: codex mcp add mailcheap --url https://news.carolekorngold.com/mcp --bearer-token-env-var MAILCHEAP_API_KEY ### Cursor ~/.cursor/mcp.json: ``` { "mcpServers": { "mailcheap": { "url": "https://news.carolekorngold.com/mcp", "headers": { "Authorization": "Bearer ${env:MAILCHEAP_API_KEY}" } } } } ``` Cursor reads MAILCHEAP_API_KEY from the environment it was opened in. If it isn't set there, put the key itself after Bearer, and keep the file out of version control. ## Endpoints ### Overview Subscribers, email results and sends per hour, as on the dashboard's first page. #### Get the overview `GET /api/v1/overview` · MCP tool `get_overview` · Full access · read-only, safe to repeat 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. - `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. ```bash curl "https://news.carolekorngold.com/api/v1/overview?timeZone=Europe%2FParis" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` ### Newsletters Sender, postal address, welcome and confirmation emails, list cleanup and archive. #### List newsletters `GET /api/v1/newsletters` · MCP tool `list_newsletters` · Full access · read-only, safe to repeat 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. No parameters. ```bash curl "https://news.carolekorngold.com/api/v1/newsletters" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Get a newsletter `GET /api/v1/newsletters/{id}` · MCP tool `get_newsletter` · Full access · read-only, safe to repeat Gets a newsletter's settings: sender, postal address, welcome and confirmation emails, list cleanup and archive. - `id` (path, string, required): The newsletter's ID or slug ```bash curl "https://news.carolekorngold.com/api/v1/newsletters/6650f1c2e9b1d4a012345678" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Create a newsletter `POST /api/v1/newsletters` · MCP tool `create_newsletter` · Full access 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@., which MailCheap sets up in a few minutes. List cleanup is on unless cleanup.enabled is false. Add a postal address before sending. - `name` (body, string, required): The newsletter's name, shown in emails and on the archive - `slug` (body, string): Lowercase letters, digits and dashes. Default: made from the name, numbered when another newsletter has it. - `imageUrl` (body, string): Square logo, 128×128 or larger: an https:// link - `fromName` (body, string): Name in the From field - `fromEmail` (body, string): The shared address (hello@., set automatically) or an address on a domain added to this account - `replyTo` (body, string): Where replies go. Empty: replies to the shared address go to the account owner. - `postalAddress` (body, string): Printed in the footer of every email. Sending needs one. - `archiveEnabled` (body, boolean): A public page for each sent issue, with a signup form - `description` (body, string): One sentence under the name on the archive, 200 characters at most - `author` (body, object): The archive's author page; the author's name is fromName - `author.bio` (body, string): Under the author's name on the archive, 160 characters at most - `author.imageUrl` (body, string): Author photo: an https:// link. The newsletter image otherwise. - `socialLinks` (body, string[]): https:// links shown on the archive, 8 at most - `requireConfirmation` (body, boolean): Confirmed opt-in: new signups get an email with a button and only join once they click it. On for new newsletters. - `cleanup` (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 - `cleanup.enabled` (body, boolean): On for new newsletters - `cleanup.issues` (body, number | null): Ignored issues in a row before the last-chance email, 2 to 100. Default 6. - `cleanup.days` (body, number | null): Days without an open, click or signup, 30 to 3650. Default 180. - `welcome` (body, object): Email sent to each new subscriber. Not sent while signups need confirming. - `welcome.enabled` (body, boolean) - `welcome.subject` (body, string) - `welcome.previewText` (body, string) - `welcome.markdown` (body, string): Markdown - `confirmation` (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. - `confirmation.subject` (body, string) - `confirmation.previewText` (body, string) - `confirmation.markdown` (body, string): Markdown that keeps the button: an HTML link like Confirm ```bash curl -X POST "https://news.carolekorngold.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}` · MCP tool `update_newsletter` · Full access · safe to repeat Changes a newsletter's settings. Send only the fields to change; nested groups (welcome, confirmation, cleanup, author) keep the fields you leave out. - `id` (path, string, required): The newsletter's ID or slug - `name` (body, string): The newsletter's name, shown in emails and on the archive - `slug` (body, string): Lowercase letters, digits and dashes, not a name MailCheap keeps like www, api or mail. The shared from address (hello@.) and the archive subdomain follow it. - `imageUrl` (body, string): Square logo, 128×128 or larger: an https:// link - `fromName` (body, string): Name in the From field - `fromEmail` (body, string): The shared address (hello@., set automatically) or an address on a domain added to this account - `replyTo` (body, string): Where replies go. Empty: replies to the shared address go to the account owner. - `postalAddress` (body, string): Printed in the footer of every email. Sending needs one. - `archiveEnabled` (body, boolean): A public page for each sent issue, with a signup form - `description` (body, string): One sentence under the name on the archive, 200 characters at most - `author` (body, object): The archive's author page; the author's name is fromName - `author.bio` (body, string): Under the author's name on the archive, 160 characters at most - `author.imageUrl` (body, string): Author photo: an https:// link. The newsletter image otherwise. - `socialLinks` (body, string[]): https:// links shown on the archive, 8 at most - `requireConfirmation` (body, boolean): Confirmed opt-in: new signups get an email with a button and only join once they click it. On for new newsletters. - `cleanup` (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 - `cleanup.enabled` (body, boolean): On for new newsletters - `cleanup.issues` (body, number | null): Ignored issues in a row before the last-chance email, 2 to 100. Default 6. - `cleanup.days` (body, number | null): Days without an open, click or signup, 30 to 3650. Default 180. - `welcome` (body, object): Email sent to each new subscriber. Not sent while signups need confirming. - `welcome.enabled` (body, boolean) - `welcome.subject` (body, string) - `welcome.previewText` (body, string) - `welcome.markdown` (body, string): Markdown - `confirmation` (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. - `confirmation.subject` (body, string) - `confirmation.previewText` (body, string) - `confirmation.markdown` (body, string): Markdown that keeps the button: an HTML link like Confirm ```bash curl -X PATCH "https://news.carolekorngold.com/api/v1/newsletters/6650f1c2e9b1d4a012345678" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"replyTo":"jane@example.com","requireConfirmation":true}' ``` #### Send a test of the welcome email `POST /api/v1/newsletters/{id}/welcome-test` · MCP tool `send_welcome_test_email` · Full access · reaches outside MailCheap Sends the saved welcome email to the account owner's address, switched on or not. It counts toward the plan's emails. - `id` (path, string, required): The newsletter's ID or slug ```bash curl -X POST "https://news.carolekorngold.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` · MCP tool `list_campaigns` · Full access · read-only, safe to repeat 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. - `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 ```bash curl "https://news.carolekorngold.com/api/v1/campaigns?status=sent&limit=10" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Get a campaign `GET /api/v1/campaigns/{id}` · MCP tool `get_campaign` · Full access · read-only, safe to repeat Gets a campaign with its content, stats and, for drafts, what would block sending it now. - `id` (path, string, required): The campaign's ID ```bash curl "https://news.carolekorngold.com/api/v1/campaigns/6650f1c2e9b1d4a012345678" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Get a campaign's report `GET /api/v1/campaigns/{id}/report` · MCP tool `get_campaign_report` · Full access · read-only, safe to repeat Delivery, open, click, bounce, complaint and unsubscribe rates of a sent campaign, its list cleanup emails, results by inbox provider, and how many contacts a capped send hasn't reached yet. - `id` (path, string, required): The campaign's ID ```bash curl "https://news.carolekorngold.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/report" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Create a draft campaign `POST /api/v1/campaigns` · MCP tool `create_campaign` · Full access Creates a draft. Nothing is sent: review it in the dashboard or with get_campaign, then send_test_email, schedule_campaign or send_campaign. - `newsletter` (body, string): 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 - `previewText` (body, string): 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 - `content` (body, string): 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. ```bash curl -X POST "https://news.carolekorngold.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}` · MCP tool `update_campaign` · Full access · safe to repeat Changes a draft or scheduled campaign's subject, preview text or content. Send only the fields to change; format goes with content. Sent campaigns can't change. - `id` (path, string, required): The campaign's ID - `subject` (body, string): Subject line, 200 characters at most - `previewText` (body, string): 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. - `content` (body, string): The body in that format, 500 KB at most ```bash curl -X PATCH "https://news.carolekorngold.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}` · MCP tool `delete_campaign` · Full access · can't be undone, safe to repeat Deletes a draft or scheduled campaign: it leaves every list and a scheduled send never goes out. Sent campaigns can't be deleted. - `id` (path, string, required): The campaign's ID ```bash curl -X DELETE "https://news.carolekorngold.com/api/v1/campaigns/6650f1c2e9b1d4a012345678" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Duplicate a campaign `POST /api/v1/campaigns/{id}/duplicate` · MCP tool `duplicate_campaign` · Full access Copies a campaign's subject, preview text and content into a new draft. - `id` (path, string, required): The campaign's ID ```bash curl -X POST "https://news.carolekorngold.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/duplicate" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Send a test email `POST /api/v1/campaigns/{id}/test` · MCP tool `send_test_email` · Full access · reaches outside MailCheap 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. - `id` (path, string, required): The campaign's ID ```bash curl -X POST "https://news.carolekorngold.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/test" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Schedule a campaign `POST /api/v1/campaigns/{id}/schedule` · MCP tool `schedule_campaign` · Full access · can't be undone, safe to repeat, reaches outside MailCheap 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. On MailCheap Cloud, during an account's first 30 days of sending, campaigns go out over hours, the first over 24 hours, the next two over 16 and 12, then each over 8 (sendingUntil). 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. - `id` (path, string, required): The campaign's ID - `scheduledAt` (body, string, required): 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. ```bash curl -X POST "https://news.carolekorngold.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` · MCP tool `unschedule_campaign` · Full access · safe to repeat Turns a scheduled campaign back into a draft, so it doesn't go out. - `id` (path, string, required): The campaign's ID ```bash curl -X POST "https://news.carolekorngold.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/unschedule" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Send a campaign now `POST /api/v1/campaigns/{id}/send` · MCP tool `send_campaign` · Full access · can't be undone, reaches outside MailCheap Sends a draft or scheduled campaign now to the newsletter's active contacts, 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. On MailCheap Cloud, during an account's first 30 days of sending, campaigns go out over hours, the first over 24 hours, the next two over 16 and 12, then each over 8 (sendingUntil). 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. - `id` (path, string, required): 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. ```bash curl -X POST "https://news.carolekorngold.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` · MCP tool `send_campaign_to_more` · Full access · can't be undone, reaches outside MailCheap 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. - `id` (path, string, required): The campaign's ID - `additional` (body, integer): How many more contacts. Default: everyone who hasn't received it. ```bash curl -X POST "https://news.carolekorngold.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` · MCP tool `pause_campaign` · Full access · safe to repeat Stops a campaign that is sending. Emails already sent stay sent; the rest wait until resume_campaign. - `id` (path, string, required): The campaign's ID ```bash curl -X POST "https://news.carolekorngold.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/pause" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Resume a paused campaign `POST /api/v1/campaigns/{id}/resume` · MCP tool `resume_campaign` · Full access · can't be undone, reaches outside MailCheap 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. - `id` (path, string, required): The campaign's ID ```bash curl -X POST "https://news.carolekorngold.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/resume" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Update a campaign's archive page `PATCH /api/v1/campaigns/{id}/archive` · MCP tool `update_campaign_archive` · Full access · safe to repeat Changes the path of a campaign's archive page (/p/), or pins a sent issue to the top of the archive. Works on sent campaigns too. - `id` (path, string, required): 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 ```bash curl -X PATCH "https://news.carolekorngold.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` · MCP tool `preview_campaign_cleanup` · Full access · read-only, safe to repeat 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. - `id` (path, string, required): 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 ```bash curl "https://news.carolekorngold.com/api/v1/campaigns/6650f1c2e9b1d4a012345678/cleanup-preview" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` ### Contacts Search, signups, imports with checks, status changes and exports. #### List contacts `GET /api/v1/contacts` · MCP tool `list_contacts` · Full access · read-only, safe to repeat Lists contacts, newest signups first, 50 a page. Filter by newsletter, status or the start of the email address; pass nextCursor back as cursor for the next page. counts has every status for the same filters. - `newsletter` (query, string): Only this newsletter's: its ID or slug. Default: every newsletter. - `status` (query, "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant"): Only contacts with this status - `search` (query, string): Contacts whose email starts with this - `limit` (query, integer): Contacts per page, 50 by default, 100 at most - `cursor` (query, string): nextCursor from the previous page ```bash curl "https://news.carolekorngold.com/api/v1/contacts?status=active&search=jane" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Get a contact `GET /api/v1/contacts/{id}` · MCP tool `get_contact` · Full access · read-only, safe to repeat Gets one contact by ID or email address, with its status, dates and engagement. - `id` (path, string, required): 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 ```bash curl "https://news.carolekorngold.com/api/v1/contacts/6650f1c2e9b1d4a012345678" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Add a contact `POST /api/v1/contacts` · MCP tool `add_contact` · Full access or signups only · reaches outside MailCheap 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 keep coming in over the plan's limits. A misspelled domain (gmial.com) answers validation_failed with the address it was likely meant to be; spam trap addresses and domains that can't receive email answer validation_failed too. - `newsletter` (body, string): The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest. - `email` (body, string, required): The subscriber's email address - `source` (body, string): 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. - `ip` (body, string): The visitor's IP address: one visitor gets 5 signups in 10 minutes ```bash curl -X POST "https://news.carolekorngold.com/api/v1/contacts" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email":"jane@example.com","source":"website"}' ``` #### Unsubscribe or reactivate a contact `PATCH /api/v1/contacts/{id}` · MCP tool `update_contact_status` · Full access · can't be undone, safe to repeat unsubscribed stops all emails to the contact, for good: only the person signing up again brings them back. active brings back a dormant contact; unsubscribes, bounces and complaints are final. - `id` (path, string, required): 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 - `status` (body, "active" | "unsubscribed", required): active (dormant contacts only) or unsubscribed ```bash curl -X PATCH "https://news.carolekorngold.com/api/v1/contacts/6650f1c2e9b1d4a012345678" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"status":"unsubscribed"}' ``` #### Import contacts `POST /api/v1/contacts/import` · MCP tool `import_contacts` · Full access · can't be undone, safe to repeat Adds up to 1000 contacts per call, with the same checks as the dashboard's CSV import: invalid, misspelled (gmial.com…), spam trap, role (info@, support@…), throwaway, duplicate and suppressed addresses, 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. - `newsletter` (body, string): The newsletter's ID or slug. Default: the account's first newsletter, the one it has had longest. - `consent` (body, boolean, required): Must be true: These people agreed to receive my emails. Bought or scraped lists aren't allowed. - `contacts` (body, object[], required): The rows, 1000 at most - `contacts[].email` (body, string, required): Invalid addresses are left out and counted - `contacts[].status` (body, "active" | "dormant" | "unsubscribed" | "bounced" | "complained"): active (default), dormant, unsubscribed, bounced or complained - `contacts[].subscribedAt` (body, string): When they signed up, ISO 8601 - `contacts[].emailsReceived` (body, number): Emails they got on the previous platform - `contacts[].openRate` (body, number): 0 to 1, from the previous platform: sends reach the most engaged first - `contacts[].clickRate` (body, number): 0 to 1, from the previous platform - `importId` (body, string): The importId of the first chunk, to add rows to the same import - `duplicates` (body, integer): Duplicates you removed before sending, counted in the import's report ```bash curl -X POST "https://news.carolekorngold.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"}]}' ``` #### Export contacts `GET /api/v1/contacts/export` · MCP tool `export_contacts` · Full access · read-only, safe to repeat 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. - `newsletter` (query, string): Only this newsletter's: its ID or slug. Default: every newsletter. - `status` (query, "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant"): Only contacts with this status - `search` (query, string): Contacts whose email starts with this ```bash curl "https://news.carolekorngold.com/api/v1/contacts/export?status=active" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` ### Domains Own sending domains with their DNS records, and the shared address. #### List domains `GET /api/v1/domains` · MCP tool `list_domains` · Full access · read-only, safe to repeat Lists the account's own sending domains with their DNS records and status as last checked, and each newsletter's shared address (hello@.), which works with no setup. No parameters. ```bash curl "https://news.carolekorngold.com/api/v1/domains" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Add a domain `POST /api/v1/domains` · MCP tool `add_domain` · Full access · reaches outside MailCheap 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. on PostShiba, bounce. 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. - `domain` (body, string, required): 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): Subdomain for the archive, tracked links and unsubscribe links. Default: news.. ```bash curl -X POST "https://news.carolekorngold.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` · MCP tool `check_domain` · Full access · safe to repeat, reaches outside MailCheap Asks the email provider and DNS again whether the domain's records are in. On PostShiba, a check within a minute of the last one answers what that one found. Once its archive subdomain points at MailCheap, the newsletter sending from the domain moves its archive and links there. - `id` (path, string, required): The domain's ID ```bash curl -X POST "https://news.carolekorngold.com/api/v1/domains/6650f1c2e9b1d4a012345678/check" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Remove a domain `DELETE /api/v1/domains/{id}` · MCP tool `remove_domain` · Full access · can't be undone, safe to repeat, reaches outside MailCheap Removes a domain from the email provider and its archive subdomain from MailCheap. 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. - `id` (path, string, required): The domain's ID ```bash curl -X DELETE "https://news.carolekorngold.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` · MCP tool `list_images` · Full access · read-only, safe to repeat 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. - `limit` (query, integer): Images per page, 50 by default, 100 at most - `cursor` (query, string): nextCursor from the previous page ```bash curl "https://news.carolekorngold.com/api/v1/images?limit=20" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Upload an image `POST /api/v1/images` · MCP tool `upload_image` · Full access · reaches outside MailCheap 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. - `base64` (body, string): The image file, base64 encoded; a data: URL works too - `url` (body, string): An https:// link to the image - `fileName` (body, string): Used in the stored file's name - `contentType` (body, string): The file's type, checked against its first bytes ```bash curl -X POST "https://news.carolekorngold.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` · MCP tool `list_api_keys` · Full access · read-only, safe to repeat Lists the account's API keys, revoked ones included, with their level and when they were last used. Keys themselves are never shown again. No parameters. ```bash curl "https://news.carolekorngold.com/api/v1/api-keys" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Create an API key `POST /api/v1/api-keys` · MCP tool `create_api_key` · Full access 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. - `name` (body, string, required): What the key is for, e.g. Website signups - `level` (body, "full" | "signups", required): full or signups ```bash curl -X POST "https://news.carolekorngold.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}` · MCP tool `revoke_api_key` · Full access · can't be undone, safe to repeat Revokes an API key for good: requests with it answer unauthorized from now on. A key can revoke itself. - `id` (path, string, required): The API key's ID ```bash curl -X DELETE "https://news.carolekorngold.com/api/v1/api-keys/6650f1c2e9b1d4a012345678" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### List connected apps `GET /api/v1/connected-apps` · MCP tool `list_connected_apps` · Full access · read-only, safe to repeat 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. No parameters. ```bash curl "https://news.carolekorngold.com/api/v1/connected-apps" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Disconnect an app `DELETE /api/v1/connected-apps/{id}` · MCP tool `revoke_connected_app` · Full access · can't be undone, safe to repeat 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. - `id` (path, string, required): The connected app's ID ```bash curl -X DELETE "https://news.carolekorngold.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` · MCP tool `get_billing` · Full access · read-only, safe to repeat The account's plan, subscription status and this month's usage against the plan's limits, with every plan for comparison. Works without an active plan. A self-hosted server has no billing and answers billing_off. No parameters. ```bash curl "https://news.carolekorngold.com/api/v1/billing" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ``` #### Change plan `POST /api/v1/billing/change-plan` · MCP tool `change_plan` · Full access · reaches outside MailCheap 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. - `plan` (body, "starter" | "growth" | "pro" | "scale", required): starter, growth, pro or scale - `interval` (body, "month" | "year"): month (default) or year, which costs 10 months ```bash curl -X POST "https://news.carolekorngold.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` · MCP tool `open_billing_portal` · Full access · reaches outside MailCheap 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. No parameters. ```bash curl -X POST "https://news.carolekorngold.com/api/v1/billing/portal" \ -H "Authorization: Bearer $MAILCHEAP_API_KEY" ```