# MailCheap

> The affordable newsletter for the agentic era: a newsletter app where you pay for the emails you send, not for dormant subscribers, for a fraction of what other platforms charge. Write and schedule issues, send them to your list and publish them on the web from the dashboard, or let an AI agent do it: everything a customer does in the dashboard also works through a REST API and an MCP server, with the same checks and limits.

REST API: https://newsletter.riccardobelli.com/api/v1, with Authorization: Bearer <API key>. MCP server (Streamable HTTP): https://newsletter.riccardobelli.com/mcp, same key, or OAuth for apps like ChatGPT, Claude and Grok Bot.

## API and MCP

- [Getting started](https://newsletter.riccardobelli.com/docs): Make a first request and connect an AI assistant.
- [Authentication](https://newsletter.riccardobelli.com/docs/authentication): API keys, their two levels and the rate limits.
- [Errors](https://newsletter.riccardobelli.com/docs/errors): The error shape and every code.
- [MCP](https://newsletter.riccardobelli.com/docs/mcp): The MCP server, its tools and setup for ChatGPT, Claude, Grok Bot, Claude Code, Codex and Cursor.
- [API reference](https://newsletter.riccardobelli.com/docs/api): Every endpoint with its parameters and an example.
- [OpenAPI document](https://newsletter.riccardobelli.com/api/v1/openapi.json): the API as OpenAPI 3.1.
- [Full reference](https://newsletter.riccardobelli.com/llms-full.txt): every endpoint and MCP tool in Markdown.

## Help

How MailCheap works, for the people who use it.

- [Getting started](https://newsletter.riccardobelli.com/help/getting-started): Sign in, set up your newsletter and send your first issue.
- [Newsletter settings](https://newsletter.riccardobelli.com/help/newsletters): Name, sender, website, signups and the emails new subscribers get.
- [Sender addresses and domains](https://newsletter.riccardobelli.com/help/sender-addresses): Send from the shared address, or from your own domain once its DNS records are in.
- [Website and signups](https://newsletter.riccardobelli.com/help/website): Each newsletter's website, its issue pages, and how people sign up.
- [Design and themes](https://newsletter.riccardobelli.com/help/design): Pick a theme for your website and emails, then change its colors, fonts and shapes.
- [Contacts](https://newsletter.riccardobelli.com/help/contacts): Statuses, first names, tags and fields, segments, adding people by hand, exports and deleting.
- [Importing contacts](https://newsletter.riccardobelli.com/help/importing-contacts): Bring your list from another platform as a CSV file, with names, tags and fields, and what the import leaves out.
- [List cleanup](https://newsletter.riccardobelli.com/help/list-cleanup): What happens to contacts who stop opening: a last-chance email, then dormant.
- [Writing an issue](https://newsletter.riccardobelli.com/help/writing): The editor, pictures, moving blocks, first names, the preview and test emails.
- [Sending and scheduling](https://newsletter.riccardobelli.com/help/sending): The checks before sending, send now or later, who gets it, first sends in steps and reports.
- [Bounces, complaints and pauses](https://newsletter.riccardobelli.com/help/deliverability): What bounces and spam complaints do, when a send pauses and when an account is blocked.
- [API and AI assistants](https://newsletter.riccardobelli.com/help/api-and-ai): Run everything from code, or from ChatGPT, Claude and other assistants.
- [Your account](https://newsletter.riccardobelli.com/help/account): Signing in, connected apps, and deleting or restoring your account.

## Endpoints

### Overview

- [Get the overview](https://newsletter.riccardobelli.com/docs/api#get-overview): GET /api/v1/overview (MCP tool get_overview)

### Newsletters

- [List newsletters](https://newsletter.riccardobelli.com/docs/api#list-newsletters): GET /api/v1/newsletters (MCP tool list_newsletters)
- [Get a newsletter](https://newsletter.riccardobelli.com/docs/api#get-newsletter): GET /api/v1/newsletters/{id} (MCP tool get_newsletter)
- [Create a newsletter](https://newsletter.riccardobelli.com/docs/api#create-newsletter): POST /api/v1/newsletters (MCP tool create_newsletter)
- [Update a newsletter](https://newsletter.riccardobelli.com/docs/api#update-newsletter): PATCH /api/v1/newsletters/{id} (MCP tool update_newsletter)
- [List themes](https://newsletter.riccardobelli.com/docs/api#list-themes): GET /api/v1/themes (MCP tool list_themes)
- [Get the signup form](https://newsletter.riccardobelli.com/docs/api#get-signup-form): GET /api/v1/newsletters/{id}/signup-form (MCP tool get_signup_form)
- [Check a slug](https://newsletter.riccardobelli.com/docs/api#check-newsletter-slug): GET /api/v1/newsletters/slugs/{slug} (MCP tool check_newsletter_slug)
- [Send a test of the welcome email](https://newsletter.riccardobelli.com/docs/api#send-welcome-test-email): POST /api/v1/newsletters/{id}/welcome-test (MCP tool send_welcome_test_email)

### Campaigns

- [List campaigns](https://newsletter.riccardobelli.com/docs/api#list-campaigns): GET /api/v1/campaigns (MCP tool list_campaigns)
- [Get a campaign](https://newsletter.riccardobelli.com/docs/api#get-campaign): GET /api/v1/campaigns/{id} (MCP tool get_campaign)
- [Get a campaign's report](https://newsletter.riccardobelli.com/docs/api#get-campaign-report): GET /api/v1/campaigns/{id}/report (MCP tool get_campaign_report)
- [Create a draft campaign](https://newsletter.riccardobelli.com/docs/api#create-campaign): POST /api/v1/campaigns (MCP tool create_campaign)
- [Update a draft campaign](https://newsletter.riccardobelli.com/docs/api#update-campaign): PATCH /api/v1/campaigns/{id} (MCP tool update_campaign)
- [Delete a draft campaign](https://newsletter.riccardobelli.com/docs/api#delete-campaign): DELETE /api/v1/campaigns/{id} (MCP tool delete_campaign)
- [Duplicate a campaign](https://newsletter.riccardobelli.com/docs/api#duplicate-campaign): POST /api/v1/campaigns/{id}/duplicate (MCP tool duplicate_campaign)
- [Send a test email](https://newsletter.riccardobelli.com/docs/api#send-test-email): POST /api/v1/campaigns/{id}/test (MCP tool send_test_email)
- [Schedule a campaign](https://newsletter.riccardobelli.com/docs/api#schedule-campaign): POST /api/v1/campaigns/{id}/schedule (MCP tool schedule_campaign)
- [Cancel a scheduled send](https://newsletter.riccardobelli.com/docs/api#unschedule-campaign): POST /api/v1/campaigns/{id}/unschedule (MCP tool unschedule_campaign)
- [Send a campaign now](https://newsletter.riccardobelli.com/docs/api#send-campaign): POST /api/v1/campaigns/{id}/send (MCP tool send_campaign)
- [Send a campaign to more contacts](https://newsletter.riccardobelli.com/docs/api#send-campaign-to-more): POST /api/v1/campaigns/{id}/send-more (MCP tool send_campaign_to_more)
- [Pause a campaign](https://newsletter.riccardobelli.com/docs/api#pause-campaign): POST /api/v1/campaigns/{id}/pause (MCP tool pause_campaign)
- [Resume a paused campaign](https://newsletter.riccardobelli.com/docs/api#resume-campaign): POST /api/v1/campaigns/{id}/resume (MCP tool resume_campaign)
- [Update a campaign's archive page](https://newsletter.riccardobelli.com/docs/api#update-campaign-archive): PATCH /api/v1/campaigns/{id}/archive (MCP tool update_campaign_archive)
- [Preview the list cleanup of a send](https://newsletter.riccardobelli.com/docs/api#preview-campaign-cleanup): GET /api/v1/campaigns/{id}/cleanup-preview (MCP tool preview_campaign_cleanup)

### Contacts

- [List contacts](https://newsletter.riccardobelli.com/docs/api#list-contacts): GET /api/v1/contacts (MCP tool list_contacts)
- [Get a contact](https://newsletter.riccardobelli.com/docs/api#get-contact): GET /api/v1/contacts/{id} (MCP tool get_contact)
- [Add a contact](https://newsletter.riccardobelli.com/docs/api#add-contact): POST /api/v1/contacts (MCP tool add_contact)
- [Update a contact](https://newsletter.riccardobelli.com/docs/api#update-contact): PATCH /api/v1/contacts/{id}/details (MCP tool update_contact)
- [Change a contact's status](https://newsletter.riccardobelli.com/docs/api#update-contact-status): PATCH /api/v1/contacts/{id} (MCP tool update_contact_status)
- [Tag contacts](https://newsletter.riccardobelli.com/docs/api#tag-contacts): POST /api/v1/contacts/tag (MCP tool tag_contacts)
- [Untag contacts](https://newsletter.riccardobelli.com/docs/api#untag-contacts): POST /api/v1/contacts/untag (MCP tool untag_contacts)
- [Delete a contact](https://newsletter.riccardobelli.com/docs/api#delete-contact): DELETE /api/v1/contacts/{id} (MCP tool delete_contact)
- [Import contacts](https://newsletter.riccardobelli.com/docs/api#import-contacts): POST /api/v1/contacts/import (MCP tool import_contacts)
- [Get an import](https://newsletter.riccardobelli.com/docs/api#get-import): GET /api/v1/contacts/imports/{id} (MCP tool get_import)
- [List imports](https://newsletter.riccardobelli.com/docs/api#list-imports): GET /api/v1/contacts/imports (MCP tool list_imports)
- [Export contacts](https://newsletter.riccardobelli.com/docs/api#export-contacts): GET /api/v1/contacts/export (MCP tool export_contacts)
- [List tags](https://newsletter.riccardobelli.com/docs/api#list-contact-tags): GET /api/v1/contacts/tags (MCP tool list_contact_tags)
- [List contact fields](https://newsletter.riccardobelli.com/docs/api#list-contact-fields): GET /api/v1/contacts/fields (MCP tool list_contact_fields)
- [Create a contact field](https://newsletter.riccardobelli.com/docs/api#create-contact-field): POST /api/v1/contacts/fields (MCP tool create_contact_field)
- [Delete a contact field](https://newsletter.riccardobelli.com/docs/api#delete-contact-field): DELETE /api/v1/contacts/fields/{key} (MCP tool delete_contact_field)

### Segments

- [List segments](https://newsletter.riccardobelli.com/docs/api#list-segments): GET /api/v1/segments (MCP tool list_segments)
- [Get a segment](https://newsletter.riccardobelli.com/docs/api#get-segment): GET /api/v1/segments/{id} (MCP tool get_segment)
- [Count a segment's contacts](https://newsletter.riccardobelli.com/docs/api#count-segment): POST /api/v1/segments/count (MCP tool count_segment)
- [Create a segment](https://newsletter.riccardobelli.com/docs/api#create-segment): POST /api/v1/segments (MCP tool create_segment)
- [Update a segment](https://newsletter.riccardobelli.com/docs/api#update-segment): PATCH /api/v1/segments/{id} (MCP tool update_segment)
- [Delete a segment](https://newsletter.riccardobelli.com/docs/api#delete-segment): DELETE /api/v1/segments/{id} (MCP tool delete_segment)

### Domains

- [List domains](https://newsletter.riccardobelli.com/docs/api#list-domains): GET /api/v1/domains (MCP tool list_domains)
- [Add a domain](https://newsletter.riccardobelli.com/docs/api#add-domain): POST /api/v1/domains (MCP tool add_domain)
- [Check a domain's DNS records](https://newsletter.riccardobelli.com/docs/api#check-domain): POST /api/v1/domains/{id}/check (MCP tool check_domain)
- [Remove a domain](https://newsletter.riccardobelli.com/docs/api#remove-domain): DELETE /api/v1/domains/{id} (MCP tool remove_domain)

### Images

- [List images](https://newsletter.riccardobelli.com/docs/api#list-images): GET /api/v1/images (MCP tool list_images)
- [Upload an image](https://newsletter.riccardobelli.com/docs/api#upload-image): POST /api/v1/images (MCP tool upload_image)

### API keys

- [List API keys](https://newsletter.riccardobelli.com/docs/api#list-api-keys): GET /api/v1/api-keys (MCP tool list_api_keys)
- [Create an API key](https://newsletter.riccardobelli.com/docs/api#create-api-key): POST /api/v1/api-keys (MCP tool create_api_key)
- [Revoke an API key](https://newsletter.riccardobelli.com/docs/api#revoke-api-key): DELETE /api/v1/api-keys/{id} (MCP tool revoke_api_key)
- [List connected apps](https://newsletter.riccardobelli.com/docs/api#list-connected-apps): GET /api/v1/connected-apps (MCP tool list_connected_apps)
- [Disconnect an app](https://newsletter.riccardobelli.com/docs/api#revoke-connected-app): DELETE /api/v1/connected-apps/{id} (MCP tool revoke_connected_app)

### Billing

- [Get the plan and usage](https://newsletter.riccardobelli.com/docs/api#get-billing): GET /api/v1/billing (MCP tool get_billing)
- [Change plan](https://newsletter.riccardobelli.com/docs/api#change-plan): POST /api/v1/billing/change-plan (MCP tool change_plan)
- [Open the billing portal](https://newsletter.riccardobelli.com/docs/api#open-billing-portal): POST /api/v1/billing/portal (MCP tool open_billing_portal)