mailcheap

<p align="center"> <a href="https://mailcheap.ai"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.svg"> <img src="docs/logo.svg" alt="MailCheap" width="64" height="64"> </picture> </a> </p> <h1 align="center">MailCheap</h1> <p align="center"> Newsletters where you pay for the emails you send, not for dormant subscribers.<br> A fraction of the price of beehiiv and the like. </p> <p align="center"> <a href="https://mailcheap.ai">Website</a> · <a href="https://mailcheap.ai/docs">API docs</a> · <a href="https://mailcheap.ai/signin">Sign up for MailCheap Cloud</a> </p> <p align="center"> <a href="LICENSE"><img alt="License: AGPL-3.0" src="https://img.shields.io/github/license/marclou/mailcheap?color=blue"></a> <a href="#self-hosting"><img alt="Node.js 22 or later" src="https://img.shields.io/badge/node-22%2B-339933?logo=nodedotjs&logoColor=white"></a> <a href="https://mailcheap.ai/docs/mcp"><img alt="MCP server" src="https://img.shields.io/badge/MCP-server-0a0a0a"></a> </p>

MailCheap is a newsletter app: write an issue, send it to your list, publish it on the web, from the dashboard or from your AI agent. This repository is the whole app. Self-host it with your own Amazon SES or PostShiba account, or use MailCheap Cloud, which runs this same code.

Features

• AI agents and the dashboard. Everything the dashboard does also works from an AI agent through the MCP server, and from code through the REST API, with the same checks and limits. ChatGPT, Claude and Grok Bot connect with OAuth; Claude Code, Codex and Cursor with an API key. MCP marks sending as an action that can't be undone, so agents ask you first.
• Write, review, send. Write in an editor with slash commands, images and boxes, or send Markdown or a complete HTML email through the API and MCP. Review shows what to fix before sending: subject, preview text, unsubscribe link, Gmail's 100 KB clip, postal address, sender. Then send it, schedule it, or start with your most engaged readers and send to more later.
• Imports from beehiiv, Substack and Mailchimp. Their CSV exports import as they are, with each reader's status and signup date, and so do Kit's, MailerLite's, Buttondown's, Ghost's and EmailOctopus's.
• A website for each newsletter, on a free subdomain on MailCheap Cloud (<slug>.mailcheap.ai), or on your server: every issue gets a page search engines can find, with a signup form, an author page, share images and a sitemap.
• Sending from your own domain, with the DKIM, return path and DMARC records to add and a check for each. On MailCheap Cloud, a newsletter without a domain sends from its own shared address, hello@<slug>.mailcheap.ai.
• Deliverability protections, built in:
  • sending pace: contacts the account never emailed go out in steps, a random 2% first, then 5% more, then the rest, 30 minutes apart while their bounces and complaints stay low. On MailCheap Cloud, a domain new to Gmail also sends to its first 2,000 Gmail readers on its first day and to the others the next day;
  • list cleanup, on by default: readers who ignored several issues get one "do you still want this?" email, then stop getting issues;
  • contact cleaning: imports leave out invalid, misspelled (gmial.com), spam trap, role, throwaway and duplicate addresses, domains that can't receive email, and anyone who unsubscribed, bounced or complained before;
  • one never-email list for the whole server: an address the email provider says doesn't exist (for 180 days) or that turned out to be a spam trap (for good) is left out of every account's imports, signups and sends, and only a keyed hash of it is kept;
  • spam and bounce limits: a send pauses past 2% hard bounces or 0.08% complaints, and the account is blocked past 5% or 0.3%, or on a spam trap hit;
  • Gmail's spam rates, which Gmail never reports one complaint at a time: every email carries a Feedback-ID for Gmail's feedback loop (its campaign or newsletter, its account, its kind), and once an admin connects Google Postmaster Tools, MailCheap reads it every day. An account Gmail flags at 0.08% has its sends paused, at 0.3% it's blocked, and the admins hear when the whole domain reaches 0.1%;
  • one-click unsubscribe (RFC 8058) and a signed unsubscribe link in every email, and confirmed opt-in, on by default.
• Several newsletters: up to 3 per account, each with its own contacts, campaigns and website.
• Signups and stats: signup forms and a signup API, welcome emails, open and click tracking that leaves link scanners out, subscribers over time, and reports by inbox provider (Gmail, Outlook, Yahoo, iCloud...).

| Write, review, send | The newsletter's website | | --- | --- | | | |

All names and addresses in the screenshots are made up.

MailCheap Cloud or self-hosted

| | MailCheap Cloud | Self-hosted | | --- | --- | --- | | Price | From $19 a month for 20,000 emails | Free, plus what your provider charges per email: $0.10 to $0.16 per 1,000 on Amazon SES | | Sending | Set up for you, from hello@<slug>.mailcheap.ai or your domain | Your Amazon SES or PostShiba account, from your domain | | Website | <slug>.mailcheap.ai | /archive/<slug> on your server's domain | | Who signs in | Anyone who signs up | The emails you allow | | Limits | Emails a month and active subscribers, by plan | None | | Setup | A few minutes | About an hour, most of it waiting for DNS and production access | | Support | A chat in the dashboard | None: issues are off |

MailCheap Cloud is this repository with MAILCHEAP_CLOUD=true, which adds open sign-up, plans and Stripe billing. Only active subscribers count toward a plan, not the ones list cleanup marked dormant. Its marketing site (the landing, pricing and legal pages) isn't part of the open source. Every change to the app ships to both.

With your own sending account, you pay your provider for the emails you send: 10,000 readers and 4 issues a month is 40,000 emails, about $4 to $6 on Amazon SES.

Self-hosting

Plan for about an hour, most of it waiting for DNS and for your provider to approve production sending. Self-hosting comes without support: issues are off and setup questions go unanswered.

What you need

| Service | For | Cost | | --- | --- | --- | | MongoDB | Contacts, campaigns, stats | Free tier works | | Amazon SES or PostShiba | Sending | SES: $0.10 to $0.16 per 1,000 emails, depending on its pricing plan. PostShiba: a fixed price per cluster, invite only for now | | Upstash QStash | Background sending and scheduling | Free tier to start, then pay per message. One message sends 50 emails | | Vercel or any Node.js 22+ host | Hosting | Free tier works | | Resend (optional) | Sign-in codes and alerts. Without it, they go through SES or PostShiba | Free plan works | | Upstash Redis (optional) | Rate limits shared by every server instance | Free tier | | Amazon S3 with CloudFront, or Vercel Blob (optional) | Image uploads in the editor, the newsletter settings and the API | S3 and CloudFront: pay per use. Blob: free tier |

Without Redis, MailCheap counts the same rate limits in each server instance's memory. That still stops a script hammering a form, but on serverless hosts the limits aren't shared between instances and reset on each deploy. Add Redis before you put a signup form on a busy site. Without S3 or Blob, image uploads are off; HTML and Markdown campaigns can still use images hosted anywhere.

Environment variables

| Variable | What it does | | --- | --- | | MONGODB_URI | MongoDB connection string with a database name | | BETTER_AUTH_SECRET | Signs sessions and every link in sent emails. 32+ random characters (openssl rand -base64 48), or the server refuses to start. Rotating it signs everyone out and breaks links in emails already sent | | SUPPRESSION_HASH_KEY | Keys the hashes of the never-email list every account shares. 32+ random characters of its own, never BETTER_AUTH_SECRET, or the server refuses to start, after an upgrade too. Changing it empties the list | | ADMIN_EMAILS | Comma-separated emails that can sign in and open /admin | | ALLOWED_EMAILS | Who else can sign in: addresses and @domain entries, comma-separated | | EMAIL_FROM | From address of sign-in codes and alerts, on a domain your Resend account or email provider verified | | APP_URL | Public URL of the app, for email links and sign-in. On Vercel it defaults to the production domain | | RESEND_API_KEY | Optional: sign-in codes and alerts through Resend. Without it, they go through the email provider | | SENDING_ENABLED | Nothing goes to readers unless it's true. Sign-in codes and alerts don't wait for it | | SES_* or POSTSHIBA_* | The email provider, in step 4 | | QSTASH_* | Background sending and scheduling, in step 5 |

.env.example lists every variable with what it does, the optional ones included: Google sign-in and Postmaster Tools, image uploads, Redis, Telegram alerts, the shared domain, and MailCheap Cloud's own.

1. Database

1. Create a free cluster on MongoDB Atlas.
2. Database Access: add a user with a password and the "Read and write to any database" role.
3. Network Access: allow 0.0.0.0/0. Vercel doesn't have fixed IP addresses.
4. Connect > Drivers: copy the connection string and add a database name before the ?, like ...mongodb.net/mailcheap?retryWrites=true. That's your MONGODB_URI.

2. Deploy

1. Click Deploy above.
2. Fill in MONGODB_URI, BETTER_AUTH_SECRET (at least 32 characters; generate it with openssl rand -base64 48), SUPPRESSION_HASH_KEY (generated the same way, another value), ADMIN_EMAILS (your email) and EMAIL_FROM (like MailCheap <login@mail.example.com>, on a domain your Resend account or email provider verified). With a short secret, MailCheap refuses to start and the logs say why.
3. Sign-in codes need a way to reach you. The quickest is Resend: verify EMAIL_FROM's domain there and add RESEND_API_KEY. Without it, codes go through SES or PostShiba once step 4 is done.
4. Open https://<your-project>.vercel.app/signin and sign in with your email.

Sending stays off until you finish the next steps, so nothing goes out to readers by mistake. On any other Node.js host: npm ci && npm run build && npm start, with the same variables, behind HTTPS.